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Manual Objectives 

This manual describes the VAX Text Processing Utility (VAXTPU). This 
manual is designed primarily for reference; it is not a tutorial document. 


Intended Audience 

This manual is intended for experienced programmers who know at least 
one computer language. Some features of VAXTPU, for example, the callable 
interface and the built-in procedure FILE—PARSE, are intended for system 
programmers who have a good understanding of VAX/VMS system concepts. 
Relevant documents about the VAX/VMS operating system are listed under 
Associated Documents. 


Structure of This Document 

This manual has six sections and seven appendixes. 

• Section 1 contains an overview of VAXTPU. 

• Section 2 provides detailed information on VAXTPU data types. 

• Section 3 discusses the lexical elements of VAXTPU. These include the 
character set, identifiers, variables, constants, and reserved words, such as 
VAXTPU language statements. 

• Section 4 describes the VAXTPU built-in procedures. 

• Section 5 discusses VAXTPU program development. 

• Section 6 describes how to invoke VAXTPU. 

• Appendix A contains sample procedures written in VAXTPU. 

• Appendix B discusses terminals supported by VAXTPU. 

• Appendix C lists each VAXTPU message, its abbreviation, and its severity 
level. 

• Appendix D contains the DEC Multinational Character Set. 

• Appendix E lists the file types that VAXTPU supports. 

• Appendix F contains reference information on the Extensible VAX Editor 
(EVE). 

• Appendix G contains reference information on the EDT Keypad Emulator. 
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Associated Documents 

To leam how to use one of the editing interfaces provided with VAXTPU, 
read the appropriate manual. This manual contains an appendix of 
commands for each of the two interfaces. The Guide to Text Processing on 
VAX/VMS contains chapters describing both interfaces: the Extensible VAX 
Editor (EVE) and the EDT Keypad Emulator. 

The VAX/VMS Utility Routines Reference Manual contains a chapter presenting 
the VAXTPU callable interface. 

The VAX/VMS System Messages and Recovery Procedures Reference Manual 
contains the VAXTPU messages, as well as an explanation and suggested 
user action for each message. The messages are listed alphabetically by the 
abbreviation for the message text. 

The Introduction to the VAX/VMS Document Set briefly describes all VAX/VMS 
system documentation, defining the intended audience for each manual and 
providing a synopsis of each manual's contents. 

The VAX/VMS DCL Dictionary describes the VAX/VMS commands that help 
you in creating, copying, and printing files containing VAXTPU programs. 

The VAX/VMS System Routines Reference Volume contains information about 
system services, routines of the run-time library, VAX RMS services, and 
utility routines. 


Conventions Used in This Document 

The following conventions are used in this document: 


Convention Meaning 

{ I Braces enclose a mandatory portion of a general 

format. When oversized braces enclose a stacked 
list of items, you must choose one of the items. For 
example: 
f string i 
I range J 

|[ ]] Double square brackets in examples show an optional 

portion of a general format. When oversized double 
brackets enclose an item or series of items, you can 
select one of the items. For example: 

[ string 1 
range J 

/ 

|[, . . . I Double square brackets enclosing a comma and 

horizontal ellipsis mean that you can repeat the 
preceding item one or more times, separating two or 
more items with commas. For example: 

parameter 0!,...]] 

Vertical ellipses in a figure or example mean that not 
all of the statements are shown. 
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Convention 

Meaning 

UPPERCASE letters 
and special symbols 

Uppercase letters and special symbols in syntax 
descriptions and sample procedures indicate VAXTPU 
reserved words and predeclared identifiers, and other 
user input which must be typed exactly as shown. 

For example: 

PROCEDURE 

UNDERLINE 


String constants are shown in lowercase to 
emphasize that they are strings. However, they, 
too, must be typed exactly as shown. 



lowercase letters 

Lowercase letters in syntax descriptions and sample 
procedures represent elements that you must replace 
according to the description in the text. For example, 
when a data type, such as buffer, is used in a syntax 
example, replace it with the variable name assigned to 
the data item when it was created. In the following 
assignment statement, my—buffer—variable is the 
variable name assigned to the buffer you are creating: 



my.buflar.varlable :« 

CREATE.BUFFER ('my.buffer.name', 'my_flle_naffle') 



To specify a buffer as a parameter for a VAXTPU 
built-in procedure, use the variable for the buffer. For 
example, to erase the contents of the buffer created 
in the preceding statement, enter the following: 



ERASE (my.buffer.varlable) 


Red ink 

Red ink in examples shows all user-entered 
commands at the DCL level. 


Black ink 

Black ink in examples shows all output lines and 
prompting characters that the system displays at the 
DCL level. 


1 RETURN1 

A symbol with a one- to six-character abbreviation 
indicates that you press a key on the terminal, for 
examole 1 return I. In Aooendix F, the kevs that 
are equivalent to EVE commands are boxed for 
ease in viewing, even though they are not shown in 
interactive examples. Assume that you must press 

1 return] after tvoino a command or other inout to the 
system unless instructed otherwise. 


ICTRL/xl 

CTRL/x indicates that you press the key labeled CTRL 
while you simultaneously press another key. For 
example, CTRL/C, CTRL/Y, CTRL/0. 


user— 

Many of the sample procedures in this manual have 
the prefix user— as a part of the procedure name. 
DIGITAL suggests that you replace the prefix user 
with your initials. This or some other convention 
helps to ensure that the variables and procedure 
names that you create do not conflict with either 
VAXTPU built-in procedure names, or the procedure 
names and variables of your editing interface. 


file-spec 

Mnemonic for file specification. 
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VAXTPU programs do not require special formatting such as indentation, 
spacing, and so on. Programming examples in this manual use different 
formatting styles to show several ways of writing VAXTPU programs. Long 
statements in procedures are divided into several lines to make them easy to 
read. The formats used in this manual are not mandatory. 
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New and Changed Features 


This manual documents Version 1.2 of the VAX Text Processing Utility 
(VAXTPU) released with VAX/VMS Version 4.4. This section summarizes the 
changes in both the product and the manual from previous versions. 

VAXTPU now consists of two shared images: TPUSHR.EXE and 
TPU$CCTSHR.EXE. With VAXTPU Version 1.2, the default file type for 
section files is TPU$SECT10N instead of GBL. You must recompile all your 
section files. Section files are installable as shared images with this release. 
The preferred method of invoking a section file other than the default section 
file, is to define the logical TPUSECINI to point to the appropriate section file. 
For example: 

$ DEFINE TPUSECINI ddn:[dir]mysectlon.TPUtSECTION 

where 

dd is the device code and n is its unit number 
dir is the directory name 

mysection is the file name for the section file to be invoked. 

Key maps (and key-map lists) are a new feature of VAXTPU. Key maps 
provide the ability to group sets of key definitions by name. With key maps, 
you can easily and quickly change entire sets of key definitions. Key maps 
and key-map lists are saved in your section file. The addition of key maps 
has caused some built-in procedures to be modified and others to be created. 

VAXTPU Version 1.2 includes a new parameter to the qualifier /DISPLAY 
for the command EDIT/TPU. The format for the qualifier /DISPLAY is as 
follows: 

EDIT/TPU/DISPLAY I « tile-spec I 

The default file specification is TPU$CCTSHR, the screen management image 
for terminals that respond to ANSI control functions and that operate in ANSI 
mode. 

The following built-in procedures have been modified: 

• DEFINE_KEY 

• GET_INFO 

• JOURNAL-OPEN 

• LOOKUP-KEY 

• SCROLL 

• SET 

• SHOW 


• UNDEFINE-KEY 




New and Changed Features 


The following built-in procedures are new: 

• ADD_KEY_MAP 

• CREATE_KEY_MAP 

• CREATE_KEY_MAP_LIST 

• REMOVE_KEY_MAP 

The following are new keywords (and parameters to certain built-in 
procedures): 

• DEF1NED_KEY 

• KEY_MAP 

• KEY_MAPS 

• KEY_MAP_LIST 

• KEY_MAP_LISTS 

• SELF_INSERT 

• UNDEF1NED_KEY 

• SPECIAL-GRAPHICS 

The following error messages are either new or modified: 

• TPU$_DUPKEYMAP 

• TPU$_DUPKEYMAPL1ST 

• TPU$_NOKEYMAP 

• TPU$_NOKEYMAP 

• TPU$_KEYMAPNOTFND 

• TPU$_EMPTYKMLIST 

• TPU$_COMPILED 

• TPU$_CTRLCEXIT 

• TPU$_JOURNALCLOSE 

• TPU$_REALLYRECOVER 

• TPU$_BADJOUTERM 

• TPU$_BADJOUPAGE 

• TPU$_BADJOUWIDTH 

• TPU$_BADJOUEDIT 

• TPU$_BADJOUEIGHT 

• TPU$_BADJOULINE 
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New and Changed Features 


• TPU$_BADJOUSEC 

• TPU$_BADJOUCOM 

• TPU$_BADJOUINPUT 

• TPU$_CTRLCJOU 

Section 7 in the previous editions of this manual described the callable 
interface for VAXTPU. This material is now located in the VAX/VMS Utility 
Routines Reference Manual. 

Appendix C in the previous editions of this manual included all possible 
return statuses for VAXTPU, as well as the appropriate explanations and 
suggested user actions. This material is now incorporated in the VAX/VMS 
System Messages and Recovery Procedures Reference Manual. Appendix C now 
simply lists the return statuses for VAXTPU and the severity level for each 
return status. 

Small technical changes were made throughout the manual as a result 
of ongoing development. Software Performance Reports, and Reader's 
Comments. Editorial changes were also made throughout the manual. 
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Overview of the VAX Text Processing Utility 


This section answers the following questions about the VAX Text Processing 
Utility (VAXTPU): 

• mat is VAXTPU? 

• What is the VAXTPU language? 

• What hardware does VAXTPU support? 

• How do I start using VAXTPU? 

• How do 1 leave VAXTPU? 

• How do 1 learn more about VAXTPU? 


1.1 What is VAXTPU? 

VAXTPU is a high performance, programmable, text processing utility. It is 
designed as a tool to aid application and system programmers in developing 
text processing interfaces. The utility includes a high-level procedural 
language, a compiler, an interpreter, and two editing interfaces written in 
VAXTPU. 

You can use the editing interfaces provided with VAXTPU without alteration 
to do text editing. You can also use the VAXTPU language to tailor the 
interfaces to suit your editing style. You can even write your own editing 
interface with VAXTPU. Programmers, for example, can use VAXTPU to 
design an editor for a specific environment. The editor or other application 
that you layer on top of VAXTPU becomes the interface between VAXTPU 
and the user. You must use one of the interfaces provided or create your own 
interface to access VAXTPU. 

You can think of VAXTPU as a base on which to layer text processing 
interfaces. The two editing interfaces included with VAXTPU, the Extensible 
VAX Editor (EVE) and the VAXTPU EDT Keypad Emulator, are good 
examples of interfaces written in VAXTPU and layered on VAXTPU. See 
Figure 1-1. 

You can write extensions for the two interfaces that are shipped with 
VAXTPU or you can write a completely separate interface for VAXTPU. 

See Figure 1-2. 

Extensions to an existing interface can be implemented with a VAXTPU 
command file (VAXTPU source code) or with a VAXTPU section file (compiled 
VAXTPU code in binary form). Because a VAXTPU section file is already 
compiled, start-up time for your interface is shorter when using a section file 
as opposed to a command file. 

To implement an interface that is entirely user-written, use a section file. 

See Section 5, VAXTPU Program Development, for information on VAXTPU 
command files and section files. 
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Figure 1-1 VAXTPU as a Base for EVE and the EDT Keypad 
Emulator 
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Figure 1-2 VAXTPU as a Base for User-Written Interfaces 
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1.1.1 The EVE Interface 

The Extensible VAX Editor (EVE) is an editing interface that is measurably 
easy to learn and fast to use. Most of the common editing functions are 
accessed by pressing a single key on the EVE keypad. As a result, people 
who have never used an editor before can quickly perform basic editing tasks. 

EVE is also a powerful and efficient editor for experienced users of text 
editors. The more advanced editing functions are accessible by entering 
commands on the EVE command line. Many of the special features of 
VAXTPU (such as multiple windows) are available with EVE commands. 
Other VAXTPU features can be accessed by entering VAXTPU statements after 
the TPU Command: prompt. To get to this prompt level, do the following: 

• Press the DO key. 

• After the prompt Command:, type TPU. 
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After the prompt TPU Command:, enter valid VAXTPU statements. 


For more information on the EVE interface, see Appendix F in this manual or 
refer to the appropriate chapter of the Guide to Text Processing on VAX/VMS. 


1.1.2 The EOT Keypad Emulator Interface 

Those EOT users who do not want to learn a new interface for basic editing 
tasks can use the VAXTPU EDT Keypad Emulator. This interface provides 
all of the functions of the EDT keypad and binds these functions to the same 
keys that EDT uses. The EDT Keypad Emulator also provides EDT users with 
a limited set of the EDT line mode commands that can be entered after the 
asterisk that appears when you press CTRL/Z. 

The EDT Keypad Emulator provides access to VAXTPU functions on the EDT 
Keypad Emulator command line after the TPU Command: prompt. To get to 
this prompt level, do the following: 

• Press the PFl key and the 7 key on the keypad. 

• After the prompt TPU command:, enter valid VAXTPU statements. 

For more information on this interface, see Appendix G in this manual or 
refer to the appropriate chapter of the Guide to Text Processing on VAX/VMS. 





1.1.3 Special Features 

VAXTPU provides the following special features in addition to the features 
normally associated with a screen-oriented editor: 

• Multiple buffers 

• Multiple windows 

• Multiple subprocesses 

• Text processing in batch mode 

• Insert or overstrike text entry 

• Free or bound cursor motion 

• Learn sequences 

• Pattern matching 

• Key definition 

• Procedural language 

• Callable interface 

If you use the EVE interface to VAXTPU, many of the special features are 
easily accessible with a single EVE command. If you use the EDT Keypad 
Emulator interface, you can access advanced features on the EDT Keypad 
Emulator command line; however, the best way to include the advanced 
features is to write an extension to the EDT Keypad Emulator interface and 
invoke VAXTPU with both the EDT Keypad Emulator and the extension. See 
Sections 5 and 6 for information on writing and using command files and 
section files to extend an interface. 
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1.2 The VAXTPU Language 

VAXTPU is a high-level procedural programming language that allows you 
to perform powerful text processing tasks. The VAXTPU language can be 
viewed as the most basic component of VAXTPU. To access the features of 
VAXTPU, write a program in the VAXTPU language and then use the utility 
to compile and execute the program. A program written in VAXTPU can be 
as simple as a single statement, or as complex as the section file that creates 
the EVE interface. 

The VAXTPU language is block-structured and is easy to learn and to use. 
VAXTPU language features include a large number of data types, relational 
operators, error interception, looping and case language statements, and 
an extensive set of built-in procedures that perform important functions. 
Comments are indicated with a single comment character (!), so that you can 
document your procedures easily. There are also capabilities for debugging 
procedures with user-written debugging programs. 


1.2.1 VAXTPU Data Types 

The VAXTPU language has an extensive set of data types. Data types are 
used to interpret the meaning of the contents of a variable. Unlike many 
languages, the VAXTPU language has no declarative statement to enforce 
which data type must be assigned to a variable. Variables in VAXTPU assume 
a data type when they are used in an assignment statement. For example, the 
following statement assigns a string data type to the variable this—van 

this.var ;= 'This can be a string at your choice.' 

The following statement assigns a window data type to the variable x. The 
window occupies 15 lines on the screen, starting at line 1, and the status line 
is OFF (not displayed). 

X := CREATE_WINDOW (1, 16, OFF) 

Many of the VAXTPU data types (for example, learn and pattern) are different 
from the data types usually found in programming languages. Following is a 
list of VAXTPU keywords used to specify data types: 

• UNSPECIFIED—The initial state of a variable after it has been compiled 
(added to the VAXTPU symbol table). 

• STRING—A character string. 

• INTEGER—An integer. 

• BUFFER—A collection of text records. The built-in procedure 
CREATE—BUFFER returns this data type as its result. 

• WINDOW—A subdivision of the screen. The built-in procedure 
CREATE—WINDOW returns this data type as its result. 

• MARKER—A character position within a buffer. The built-in procedure 
MARK returns this data type as its result. 

• RANGE—All of the text that occurs between and including two markers. 
The built-in procedure CREATE—RANGE returns this data type as its 
result. 
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• PATTERN—One or more sequences of characters. The pattern operators 
and the pattern built-in procedures return this data type as a result. 
Patterns are used with the built-in procedure SEARCH to locate specific 
text within a buffer. 

• PROGRAM—A collection of VAXTPU executable statements. The built-in 
procedure COMPILE returns this data type as its result. 

• PROCESS—A VAX/VMS subprocess. The built-in procedure 
CREATE-PROCESS returns this data type as its result. 

• LEARN—A collection of VAXTPU keystrokes. The built-in procedure 
LEARN—END returns this data type as its result. 

See Section 2 of this manual for a discussion of VAXTPU data types. 


1.2.2 VAXTPU Language Statements 

VAXTPU language statements include the following: 

• Assignment statement (:=) 

• Procedure statement (PROCEDURE - ENDPROCEDURE) 

• Repetitive statement (LOOP - EXITIF - ENDLOOP) 

• Conditional statement (IF - THEN - ELSE - ENDIF) 

• Case statement (CASE - ENDCASE) 

• Error statement (ON—ERROR - ENDON—ERROR) 

See Section 3 of this manual for a discussion of VAXTPU language statements. 


1.2.3 VAXTPU Built-In Procedures 

The VAXTPU language has many built-in procedures that perform functions 
such as screen management, key definition, text manipulation, and program 
execution. 

For example, you can use built-in procedures to create an editing interface 
with multiple windows. Multiple windows allow you to see parts of different 
files (or different parts of the same file) on your screen at the same time. The 
built-in procedure CREATE—WINDOW allows you to create and alter the 
number, position, and size of the windows on the screen. Because you can 
also create multiple buffers and associate them with windows on the screen, 
you can edit multiple files concurrently with VAXTPU. 

VAXTPU built-in procedures allow you to run more than one process 
concurrently. The built-in procedure CREATE-PROCESS allows you to 
create a subprocess within a VAXTPU session and attach a buffer to it for 
storing the output of the subprocess. The built-in procedure SPAWN allows 
you to suspend a VAXTPU session and execute commands directly at the 
DCL level. When the commands are finished executing, VAXTPU returns you 
to your editing session. 

You can use the built-in procedure DEFINE—KEY to bind a VAXTPU program 
to a particular key, or key combination. This allows you to control the 
actions that are taken when a key is pressed. The built-in procedure 
UNDEFINE—KEY removes the association between a key binding and the 
code that it previously executed. 
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You can use the built-in procedure SAVE to keep key definitions, procedures, 
and variable assignments from session to session. 

You can use built-in procedures as statements within a VAXTPU procedure, 
or as commands from either the EVE interface or the EDT Keypad Emulator 
interface. See the respective interface manual for a description of how to 
enter VAXTPU procedures or commands. See Section 4 of this manual for a 
description of each of the VAXTPU built-in procedures. 


1.2.4 User-Written Procedures 

You can write your own procedures that are a combination of VAXTPU 
language statements and calls to VAXTPU built-in procedures. After you 
write a procedure and compile it, you can use the procedure name to 
invoke it. 

The syntax for user-written procedures is simple. Procedures are delimited 
by PROCEDURE—ENDPROCEDURE statements. The body of a procedure 
can contain zero or more VAXTPU statements. Statements are separated 
by semicolons. VAXTPU procedures can return values. Procedures can be 
recursive. 

Example 1-1 is a sample procedure that uses VAXTPU language statements 
(PROCEDURE—ENDPROCEDURE) and built-in procedures (POSITION, 
BEGINNING—OF, and CURRENT-BUFFER) to move the current character 
position to the beginning of the current buffer. 

Example 1-1 Sample User-Written Procedure 


! This procedure moves the editing 
! position to the top of the buffer 
PROCEDURE user.top 

POSITION (BEGIHNING.OF (CURRENT.BUFFER)); 
ENDPROCEDURE 


Once you have compiled this procedure, you can invoke it with the name 
user—top. For information about writing procedures, see Sections 3 and 5 of 
this manual. 


1.3 Hardware That VAXTPU Supports 

VAXTPU runs on all VAX computers. On some systems, if you want to work 
with very large files, you may have to adjust your system parameters or 
divide the files into smaller segments. The reason for this is that VAXTPU 
does all of its work in memory, rather than using a work file. 

VAXTPU supports screen-oriented editing on the DIGITAL VT200 and VTIOO 
series of terminals, and on other video display terminals that respond to the 
ANSI control functions. 

One of the major goals in the design of VAXTPU was fast performance 
for screen-oriented editing. Optimum screen-oriented editing performance 
occurs when running VAXTPU from VT220 and VTIOO terminals. Some 
video display terminals have hardware behavior that does not allow optimum 
VAXTPU performance. See Appendix B, VAXTPU Terminal Support, for a list 
of hardware behavior that may adversely affect VAXTPU's performance. 
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Although you cannot use the screen-oriented features of VAXTPU on the 
VT52 series of terminals, on hardcopy terminals, or on foreign terminals 
that do not respond to ANSI control functions, you can run VAXTPU on 
these terminals with a line mode style of editing. For information on how 
to implement this style of editing, see the description of the /NODISPLAY 
qualifier in Section 6, Invoking VAXTPU, and the sample line mode editor in 
Appendix A. 


1.4 Invoking VAXTPU 

To invoke VAXTPU at the DCL level, simply type EDIT/TPU, followed by 
the name of your file, For example: 

$ EDIT/TPU text_file.li» 

This command opens text_file.lis for editing. Note that you can specify only 
one input file on the command line. You can include additional files from 
within VAXTPU later in your editing session with the built-in procedure 
READ-HLE. 

When you invoke VAXTPU with the preceding command, you are placed 
in a default editing interface. The default editing interface for VAXTPU is 
EVE. We suggest that you create a symbol like Ae following one to help you 
remember which interface you are using: 

t EVE == "EDIT/TPU" 

If you want to invoke VAXTPU with the EDT Keypad Emulator rather than 
EVE as your editing interface, enter the following command after the system 
prompt: 

« EDIT/TPU/SECTION-EDTSECINI 

Instead of t)q)ing such a long command line, you can create a DCL s)unbol 
like the following to invoke VAXTPU with the EDT Keypad Emulator 
interface. This s)m\bol also reminds you of the interface you are using. 

• EDTEM “ "EDIT/TPU/SECTION=EDTSECINI" 

Then you can merely type EDTEM at the DCL level to invoke VAXTPU with 
the EDT Ke 5 q)ad Emulator interface. The terminal screen looks similiar to the 
EDT screen, with the following exceptions: 

• [EOB] is replaced witii [End of MAIN]. 

• The last two lines on the screen are reserved for error and informational 
messages from VAXTPU. 

• The EDT prompt Command: is replaced with TPU Command:, and the 
prompt appears on the third line from the bottom of the screen. 
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1.4.1 Using EDIT/TPU Command Qualifiers 

You can use qualiflers with the EDIT/TPU command. The qualifiers control 
such items as recovery from an interrupted session and the initialization files 
that provide the interface with which you access VAXTPU. Qualifiers for 
EDIT/TPU are listed in Table 1-1. 


Table 1-1 Qualifiers to the DCL Command EDIT/TPU 


QUALIFIER 

DEFAULT 

/|[NO]ICOMMANDI=file-specl 

/COMMAND=TPUINI 

/INOICREATE 

/CREATE 

/l[NO]|DISPLAYI=file-specl 

/DISPLAY=TPU$CCTSHR 

/IINO]|JOURNAL(=file-spec| 

/JOURNAL=input_file.TJL 

/|[NO]OUTPUTI=file-specI 

/OUTPUTHnput—file.type 

/|[N01READ_0NLY 

/NOREAD_ONLY 

/INOPECOVER 

/NORECOVER 

/IN01SECTI0N[=file-spec]| 

/SECTION=TPUSECINI 


For descriptions of the EDIT/TPU command qualifiers, see Section 6.4. 


1.4.2 Using Initialization Files 

There are two kinds of initialization files that can create or customize a 
VAXTPU interface: command files and section files. 

A command file is a VAXTPU source code file that has a file type TPU. It is 
used with the VAXTPU qualifier /COMMAND=file-spec. VAXTPU tries to 
read a command file unless you specify /NOCOMMAND. 

A section file is the compiled form of VAXTPU source code. It is a binary 
file that has a TPU$SECTION file type. It is used with the qualifier 
/SECTION=file-spec. By default, the section file that creates the EVE interface 
is read when you invoke VAXTPU. You must specify a different section file 
(for example, /SECTION= my_section_file) or /NOSECTION if you do not 
want to use the EVE interface. 

Note: When you invoke VAXTPU with the /NOSECTION qualifier, no binary 
file is read to provide an interface for VAXTPU. Even the RETURN and 
DELETE keys are not defined. Use /NOSECTION when you are creating a 
new section file and do not want the procedures, variables, and definitions 
from an existing section file to be included. See Sections 5 and 6 for more 
information on /NOSECTION. 

You can use either a command file, or a section file, or both, to customize 
or extend an existing interface. A command file is generally used for minor 
customization of an interface. Because start-up time is faster with a section 
file, a section file is generally used when the customization is lengthy or 
complex, or when you are creating an interface that is not layered on one of 
the existing interfaces. 








1-8 



Overview of the VAX Text Processing Utility 


Copies of both the command files and the section files for EVE and the 
EDT Keypad Emulator are in SYS$L1BRARY. We included the command 
files on-line so that you can read the VAXTPU source code that was 
used to create two different editing interfaces. The source code file for 
EVE is SYS$LIBRARY:EVESEC1N1.TPU. The compiled binary section file 
for EVE is SYS$LIBRARY:EVESEClNI.TPU$SECTION. The source code 
file for the EDT Keypad Emulator is SYS$L1BRARY:EDTSECINI.TPU. 
The compiled binary section file for the EDT Keypad Emulator is 
SYS$LIBRARY:EDTSECINI.TPU$SECT10N. If you cannot find these files 
on your system, see your system manager. 

Section 5, VAXTPU Program Development, describes how to write and 
process command files and section files. 


1.5 Leaving VAXTPU 

When you want to leave VAXTPU, you can either QUIT or EXIT. If you QUIT 
the EVE or the EDT Keypad Emulator editing interfaces, the work that you 
have done is not saved. If you EXIT from these interfaces, the current buffer 
is written out to disk (if it was modified) and you are queried about writing 
other modified buffers to disk. 


1.6 Learning More About VAXTPU 

This manual is a reference volume for experienced programmers who want 
to program in VAXTPU. The manual assumes that you are familiar with 
programming concepts and VAX/VMS system concepts. Even though 
VAXTPU is a language that is easy to read and learn, you must study the 
language to use it successfully. 

The suggested path for learning to use VAXTPU is to pick one of the 
interfaces provided, and to read the documentation describing the interface. 
The chapter describing the EVE interface in the Guide to Text Processing on 
VAX/VMS contains tutorial material for new users of a text editor. It also 
contains material for more experienced users of text editors and tells you how 
to use VAXTPU to extend the EVE interface. 

When you are familiar with the functions that your chosen interface provides, 
you may want to extend or customize the interface. Study the source code 
that creates the interface you are using to know which procedures, variables, 
and key definitions the interface uses. Then use sample procedures to 
extend your interface. Be sure that the VAXTPU programs that you write 
to customize or extend the interface do not conflict with items that the 
interface uses. 

When you have successfully compiled and executed the VAXTPU procedures 
shown in the Guide to Text Processing on VAX/VMS, use this manual to learn 
more about the VAXTPU language. In this manual. Section 2, VAXTPU Data 
Types, Section 3, Lexical Elements of the VAXTPU Language, and Section 4, 
VAXTPU Built-in Procedures, describe the elements of the VAXTPU language. 
Section 5, VAXTPU Program Development, tells you how to use the elements 
of the language to develop programs. Section 6, Invoking VAXTPU, tells you 
how to invoke VAXTPU with the procedures and programs you 
have developed. 
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To help you leam about the VAXTPU language, this manual contains many 
examples of VAXTPU procedures and programs. Every built-in procedure in 
Section 4 has an example that is a simple, one-line VAXTPU statement using 
the built-in procedure. Many of the descriptions of the built-in procedures in 
Section 4 also have a short sample procedure that uses the built-in procedure 
in an appropriate context. Appendix A contains longer sample procedures 
that perform useful editing tasks. These procedures are merely samples; 
adapt them for your own use. You must substitute an appropriate value for 
any items in lowercase in sample procedures and syntax examples. 

Some system programmers may not want to follow the suggested path of 
learning about VAXTPU by using one of the interfaces provided. If you want 
to design your own VAXTPU interface, rather than using EVE or the EOT 
Keypad Emulator, you can find the source code for a minimal interface in 
Example 5-5. Experienced programmers can use this sample as a starting 
point for writing their own VAXTPU interface. This manual does not tell 
you how to design interfaces; however, the source code files that are used to 
create the EVE and the EOT Keypad Emulator interfaces are good examples 
of how to use VAXTPU to create editing interfaces. 
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A data type is a group of elements that "belong together"; the elements are 
all formed in the same way and are treated uniformly. The data type of a 
variable determines the operations that can be performed on it. The VAXTPU 
data types are represented by the following keywords: 

• UNSPECIHED 

• INTEGER 

• STRING 

• BUFFER 

• WINDOW 

• MARKER 

• RANGE 

• PATTERN 

• PROGRAM 

• PROCESS 

• LEARN 

Data types are used to interpret the contents of a variable. Unlike many 
programming languages, VAXTPU permits any variable to have any type of 
data as a value. VAXTPU has no declaration statement to enforce which data 
type can be assigned to a variable. VAXTPU variables assume a data type 
when they are placed on the left-hand side (LHS) of an assignment statement. 
The right-hand side (RHS) of the assignment statement determines the data 
type of the variable. 

Although you can construct variables freely, individual VAXTPU built-in 
procedures require that their parameters be specific data types. Each built-in 
procedure can operate only on certain data types. Some built-in procedures 
return a data type when they are executed. The following sections describe 
the VAXTPU data types. 


2.1 UNSPECIFIED 


An unspecified value is the initial value of a variable after it has been 
compil^ (added to the VAXTPU symbol table). In the following example, the 
built-in procedure COMPILE assigns an unspecified data type to the variable 
x: 


COMPILE Cx 1') 
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An assignment statement that creates a variable must be executed before a 
data type is assigned to the variable. In the following example, when you 
use the built-in procedure EXECUTE to run the program that is stored in the 
variable prog, the variable x is assigned an integer value: 

prog COMPILE <'x !•): 

EXECUTE (prog); 


2.2 INTEGER 


VAXTPU uses the integer data type to represent numeric data. VAXTPU 
performs only integer arithmetic. The type integer consists of the whole 
number values ranging from -2,147,483,648 to 2,147,483,647. In VAXTPU, 
an integer constant is a sequence of decimal digits; no commas or decimal 
points are allowed. 

The following example assigns an integer data type to the variable *: 

X := 12346 


2.3 STRING 


VAXTPU uses the string data type to represent character data. A value of the 
string data type can contain any of the elements of the DEC Multinational 
Character set. To specify a string constant, enclose the value in quotation 
marks. In VAXTPU, you can use either the quotation mark {") or the 
apostrophe (') as the quote delimiters for a string. The following statements 
assign a string data type to the variable x: 

X :■ 'abed'; 

X :■ "abed"; 

To specify the quote character itself within a string, type the character twice 
if you are using the same quote character as delimiters for the string. The 
following statements show how to quote an apostrophe and a quotation mark 
respectively: 

X := !The value aasigned to x la '. 

.= ..... value assigned to x Is ". 

If you use the alternate quote character as the delimiter for the string within 
which you want to specify a quote character, you do not have to type the 
character twice. The following statements show how to quote an apostrophe 
and a quotation mark respectively when the alternate quote character is used 
to delimit the string: 

X :• "'" !Tbe valus asslgnsd to x Is '. 

X :« !Tbe valus asslgnsd to x is ”. 

A null string is a string of length zero. You can assign a null string to the 
variable x in the following way: 

X " 

The maximum length for a string is 65,535 characters. 
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Many VAXTPU built-in procedures return a string data type. The built-in 
procedure ASCII, for example, returns a string for the ordinal value that you 
use as a parameter. The following statement returns the string 'K' in the 
variable my—char. 

my.char := ASCII (76) 


2.4 BUFFER 

A buffer data type is a work space for manipulating text. A buffer can be 
empty or it can contain text records. You can have multiple buffers. A 
buffer data type is returned by the built-in procedures CREATE—BUFFER, 
CURRENT-BUFFER, and GET_INFO. (CREATE-BUFFER is the only one of 
the three preceding built-in procedure that creates a new buffer. The other 
two return pointers to existing buffers.) The following statement assigns a 
buffer data type to the variable my—biif: 

my.buT :« CREATE.BOFFER ("my.bullar") 

When you use a buffer as a parameter for VAXTPU built-in procedures, 
you must use the variable name to which you assigned the buffer as the 
parameter. For example, if you want to erase the contents of the buffer 
created in the preceding statement, enter the following: 

ERASE (ny.bul) 

Note: The buffer variable, myJbuf, is the parameter, not the string "my—buffer". 
VAXTPU uses the string "my—buffer" to identify the buffer on the status 
line. 

The statement ERASE (my—buf) erases the contents of the buffer. If you want 
to delete the buffer itself, use the built-in procedure DELETE with the buffer 
variable as the parameter. 

More than one buffer variable can represent the same buffer. The following 
statement causes both myJbuf and old—buf to point to the same buffer: 

old_bul ;• ny.buf; 

A buffer remains in VAXTPU's internal list of buffers even when there is no 
buffer variable pointing to it. You can use the built-in procedure GET—INFO 
to retrieve buffers from VAXTPU's internal list. 

Creating a buffer does not necessarily cause the information contained in 
the buffer to become visible on the screen. The buffer must be associated 
with a window that is mapped to the screen for the buffer contents to be 
visible. Editing can take place in a buffer even if the buffer is not mapped to 
a window on the screen. 

The current buffer contains the current character position for editing. The 
current character position can be different from the current cursor position, 
and often each is in a different location. When the current buffer is associated 
with a visible window (one that is mapped to the screen), the current 
character position and the cursor position are the same. 
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A single buffer can be associated with 0 to 255 windows for editing purposes. 
It is often useful to have a buffer visible in two windows so that you can look 
at two separate parts of the same file. For example, you could display a set 
of declarations in one window, and code that uses the declarations in another 
window. Edits made to a buffer show up in all windows in which the buffer 
is visible, provided that the context of the current edit is visible on the screen 
in that window. 


2.5 WINDOW 


A window data type refers to an area of the screen. The built-in procedures 
CREATE-WINDOW, CURRENT-WINDOW, and GET-INFO return a 
window data type as a result. (CREATE—WINDOW is the only one of 
the three preceding built-in procedures that creates a new window.) The 
following example assigns a window data type to the variable x\ 

X := CREATE_WINDOW (1, 12, OFF) 

The first parameter specifies that the window starts at screen line number 
1, the second parameter specifies that the window is 12 lines in length, and 
the keyword OFF specifies that a status line is not to be displayed when the 
window is mapped to the screen. 


2.5.1 Window Dimensions 

Windows are defined in screen lines and columns. All windows extend the 
full width of the screen. Lines on the screen are counted from one to the 
page length of the screen, and so are the lines of a window. Columns on 
the screen are counted from one to the physical width of the screen, and so 
are the columns of a window. The minimum length for a window is one 
screen line if you do not include a status line, or two screen lines if you use 
a status line. The status line occupies the last line of the window, and by 
default contains information about the buffer and the file associated with the 
window. You can turn the display of the status line on or off. 

The maximum length of a window is the maximum number of screen lines 
on your screen. If, for example, your screen is 24 lines long, the maximum 
size for a single window is 24 lines. On the same size screen, you can have a 
maximum of 24 visible windows, if you do not use status lines. If you use a 
status line for each window, the maximum number of visible windows is 12. 


2.5.2 Creating Windows 

When you use a device that supports windows (see Appendix B for 
information on terminals that VAXTPU supports), you or the section file 
that initializes your editing interface must create and map windows. If you 
do not associate a buffer with a window and map the window to the screen, 
the only information displayed on the screen are messages that are written to 
the screen at the current cursor position. 

The built-in procedure CREATE—WINDOW defines the size and location 
of a window and specifies whether a status line is to be displayed. 
CREATE—WINDOW also adds the window to VAXTPU's internal list of 
windows available for mapping. At creation, a window is marked as being 
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not visible and not mapped and the following values for the window are 
calculated and stored: 

• Original ^op line—Screen line number of the top of the window when it 
was created. 

• Original-bottom line—Screen line number of the bottom of the window 
when it was created (does not include the status line). 

• Original-length of the window—Number of lines in the window (includes 
the status line). 


2.5.3 Window Values 


When you create a window with the built-in procedure CREATE—WINDOW, 
VAXTPU saves the values of the screen line numbers that delimit the window 
in original—top and original—bottom. When you map a window to the screen 
with the built-in procedure MAP, the window becomes visible on the screen. 
If it is the only window on the screen, its visible—top and visible—bottom 
screen line values are the same as its original—top and original-bottom values. 
You can display the original and the visible values with SHOW (WINDOWS), 
or retrieve them using the built-in procedure GET_INFO. However, if there 
is already a window on the screen, and you map another window over part 
of the first window, the values for the first window's visible—top and/or 
visible—bottom are modified. The new value for visible-length of the first 
window is different from its original—length until the second window is 
removed from the screen. 


2.5.4 Mapping Windows 

When you want a window and its associated buffer to be visible on the 

screen, use the built-in procedure MAP. Mapping a window to the screen has 

the following effects: 

• The mapped window becomes the current window and the cursor is 
moved to the current editing position in the buffer that is associated with 
the window. 

• The buffer that is associated with the window becomes the current buffer. 

• The window is marked as visible and mapped. 

• The visible—top line, visible—bottom line, and visible—length of the window 
are calculated and stored. Initially, these values are the same as the 
original values that were calculated when the window was created. (See 
the last item in the following list.) 

Mapping a window to the screen may have the following side effects: 

• The newly mapped window may occlude other windows. This happens 
when the original—top and/or original-bottom line of the newly mapped 
window overlaps the boundaries of existing visible windows. This 
overlapping can cause some windows to be totally occluded or not visible. 
Note that these windows are still marked mapped, and when the window 
that is covering them is unmapped, they may reappear on the screen 
without being explicitly remapped. 
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• If the newly mapped window segments a window into two parts, only the 
top part of the segmented window continues to be updated. The lower 
part of the segmented window is erased at the next window update. 

• The visible—top, visible—bottom, and visible—length values of a window that 
is occluded change from their original values. 

When a newly mapped window becomes the current window (the built-in 
procedures MAP, POSITION, and ADJUST-WINDOW cause this to happen), 
the cursor is placed in the current window. In addition to the current cursor 
position in the current window, there is a current position in windows that 
do not contain the cursor. The current position in a window other than the 
current window is the last location of the cursor when it was in the window. 
This concept of current position in windows that do not contain the cursor 
allows you to edit in multiple locations of a single buffer if that buffer is 
associated with more than one window. 


2.5.5 Removing Windows 

To remove a window from the screen, you can use either the built-in 
procedure UNMAP or the built-in procedure DELETE. UNMAP removes a 
window from the screen. However, the window is still in VAXTPU's internal 
list of windows. It is avaUable to be remapped to the screen without being 
recreated. DELETE removes a window from the screen and also removes 
it from VAXTPU's list of windows. It is then no longer available for future 
mapping to the screen. 

Unmapping or deleting a window has the following effects: 

• The unmapped window is marked as not visible and not mapped. 

• Another window becomes the current window and the cursor is moved to 
the last current position in that window. 

• If other windows were occluded by the window you removed from the 
screen, text from the occluded ^vindows reappears on the screen. The 
visible—top, visible-bottom, and visible—length values of the previously 
occluded windows are modified according to the lines that are returned to 
them when the occluding window is unmapped. 


2.5.6 Screen Manager 

The screen manager is the part of VAXTPU that controls the display of 
data on the screen. You can manipulate data without having it appear on a 
terminal screen (see the qualifier /NODISPLAY in Section 5). However, if 
you use VAXTPU's window capability to make your edits visible, the screen 
manager controls the screen. 

In the main control loop of VAXTPU, the screen manager is not called to 
perform its duties until all commands that are bound to the last key pressed 
have finished executing. Upon completion of all the commands, the screen 
manager updates every window to reflect the current state of that part of 
the buffer that is visible in the window. If you want to make the screen 
reflect changes to the buffer prior to the end of a procedure, use the built-in 
procedure UPDATE to force the updating of the window. Using UPDATE 
is recommended for built-in procedures such as CURRENT-COLUMN that 
query VAXTPU for the current cursor position. To ensure that the cursor 
position returned is the correct location (up to the point of the most recently 
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issued command), use UPDATE prior to using CURRENT-COLUMN or 
CURRENT-ROW. 


2.5.7 Getting Information on Windows 

There are two VAXTPU built-in procedures that return information about 
windows: GETLINFO and SHOW (WINDOWISI). 

GET—INFO returns information that you can store in a variable. You can get 
information about the visible and original values of windows, as well as about 
other attributes that you have set up for your window environment. See the 
description of GET—INFO in Section 4. 

SHOW (WINDOW) or SHOW (WINDOWS) puts information about 
windows in the SHOW—BUFFER. If you use an editing interface that has 
an INFO—WINDOW, you can display the SHOW—BUFFER information in 
INFO—WINDOW. If you use the EDT Keypad Emulator interface, the SHOW 
(WINDOWS) statement displays information similar to that in Figure 2-1. 

Figure 2-1 SHOW (WINDOWS) Display 


Window; MAIN.WINDOW 
Visible window nomber; 1 
Buffer; MAIN.BOFFEB 
Video; None 

Status.llne; Off Text; Blank_tab8 Pad; Off 

Most recent visible cursor was at row 14 column 1 

Visible. Top; 1 Bottom; 21 Original. Top; 1 Bottom; 21 

Scroll. Top; 6 Bottom; 7 Amount; 0 
Width; 80 Shlft.amount; 0 

Window; INFO.WINDOW 
Not Visible 
Buffer; Not Happed 
Video; Reverse 

Status.llne; On Text; Blank.tab8 
Host recent visible cursor was UNKNOWN 
Visible. Top; 1 Bottom; 20 
Scroll. Top; 0 Bottom; 0 Amount; 0 
Width; 80 Shlft.amount; 0 

Window; MESSAGE.WINDOW 
Visible window number; 2 
Buffer; MES8AGE.BUFFER 
Video; None 

Status.llne; Off Text; Blank.tabB Pad; Off 

Most recent visible cursor was at row 24 column 1 

Visible. Top; 23 Bottom; 24 Original. Top; 23 Bottom; 24 

Scroll. Top; 0 Bottom; 0 Amount; 0 
Width; 80 Shift.amount; 0 


Pad; On 

Original. Top; 1 Bottom; 20 


Note: The value entered after Window: is the variable most recently associated 
with the window. 
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2.5.8 Terminals That Do Not Support Windows 

VAXTPU supports windows only for ANSI CRTs. (See Appendix B if you 
need more information about VAXTPU terminal support.) If the logical 
name SYS$INPUT is pointing to an unsupported device, windows cannot be 
used. When you are working on an unsupported device, you must specify 
/NODISPLAY when you invoke VAXTPU, or the utility exits with an error 
condition. The qualifier /NODISPLAY informs VAXTPU that you do not 
expect the device from which you are issuing VAXTPU commands to support 
screen-oriented editing. VAXTPU displays messages on an unsupported 
device at the current location. When you use the qualifier /NODISPLAY, any 
statements that try to manipulate the window data type return an error status. 
See Section 5 for more information on the /NODISPLAY qualifier. 


2.6 MARKER 


A marker data type is a reference point that is associated with a character 
position within a buffer. The marker data type is returned by the built-in 
procedures MARK, SELECT, BEGINNING_OF, END_OF, and GET_INFO. 

If the character that a marker is associated with moves within the buffer, the 
marker moves with it. If the character that a marker is associated with is 
deleted, the marker moves to the next closest character. To remove a marker, 
use the built-in procedure DELETE with the marker as a parameter (DELETE 
(markl)) or set all variables referring to the marker to integer zero 
(markl := 0). 

The following example assigns a marker data type to the variable x: 

X :• MARK (HONE) 

The variable x is now associated with the character position that was the 
current character position within the buffer when the assignment statement 
was executed. You can cause a marker to be displayed with varying video 
attributes (BLINK, BOLD, REVERSE, UNDERLINE). The keyword NONE, 
in the preceding example, specifies that the marker does not have any video 
attributes. 


2.7 RANGE 


A range data type represents all the text between (and including) 
two markers. You can form a range with the built-in procedure 
CREATE—RANGE. A range is associated with characters within a buffer. If 
the characters within a range move, the range moves with them. If characters 
are added or deleted between two markers that delimit a range, the size of 
the range changes. If all the characters in a range are delete^ the range 
moves to the next closest character. To remove a range, use the built-in 
procedure DELETE with the range as a parameter (DELETE (my_range)) or 
set all variables referring to the range to integer zero (my_range := 0). 

Deleting a range does not remove the characters of the range from the 
buffer; it merely removes the range data type. To remove the characters of 
a range, use the built-in procedure ERASE with the range as a parameter. 

For example, ERASE (my—range) removes all the characters in my—range, 
but it does not remove the range structure. That is done with the built-in 
procedure DELETE, as explained in the preceding paragraph. The range data 
type is returned by the built-in procedures CREATE_RANGE, SEARCH, 
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SELECT-RANGE, and GET—INFO. The following example assigns a range 
data type to the variable x: 

X :• CREATE_RANGE (rnarkl. nark2, UNDERLINE) 

You can cause a range to be displayed with varying video attributes 
(BLINK, BOLD, REVERSE, UNDERLINE). The keyword UNDERLINE, in 
the preceding example, specifies that the characters in the range will be 
underlined when they appear on the screen. 


2.8 PATTERN 








A pattern is a structure that represents certain character sequences within a 
buffer. Patterns are used as parameters for the built-in procedure SEARCH to 
help you locate specific text within a buffer. To create a pattern, use VAXTPU 
pattern operators (I, &, @) to connect any of the following: 

• String constants 

• String variables 

• Pattern variables 

• Pattern built-in procedures 

• Parentheses (to enclose expressions) 

Patterns can be simple or complex structures. A simple pattern can be 
composed of sets of strings connected by one of the pattern operators. The 
following example indicates that patl matches the string 'abc' followed by the 
string 'def': 

patl 'abc* ft 'def 

A more complex pattern uses pattern built-in procedures and existing patterns 
to form a new pattern. The following example indicates that patl matches the 
string 'abc' followed by the longest string of characters that contains any part 
of the string '12345': 

pat2 ;« 'abc* R SPAN ('12346') 

Patl matches the string 'abcl23' in the text string "xyzabcl23def". 

Because a pattern is a data structure, you can assign a pattern to a variable 
and then use the variable as a parameter for the built-in procedure SEARCH. 
The built-in procedure SEARCH looks for the character sequences that are 
specified by the pattern that you use as a parameter. If the built-in procedure 
SEARCH ^ds a match for the pattern, it treats the parts of a pattern as a 
single entity, and returns the text that matches the pattern as a range. You 
can store the range that is returned in a variable. 

The following example uses strings and pattern operators to create a pattern 
data type that is stored in the variable my—pat. The variable is then used 
with the built-in procedure SEARCH in a FORWARD direction. If SEARCH 
finds a match for my—pat, the range of matching text is stored in the variable 
match-range. The built-in procedure POSITION causes the current position 
to move to the beginning of match-range. 

my.pat :• Cabc' I 'def') A 
match.range SEARCH (my.pat, FORWARD); 

POSITION (match_range); 
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2.8.1 Pattern Built-In Procedures 

The pattern data type is returned by the following built-in procedures: 

• ANY—Matches any single character in the string you use as a parameter. 

• ARB—Matches a sequence of characters of the length you specify. 

• LINE—BEGIN—Matches the beginning-of-line condition. 

• LINE—END—Matches the end-of-line condition. 

• MATCH—Matches a sequence of characters starting at the current 
character position and continuing up to and including the string that 
you specify as a parameter for MATCH. 

• NOTANY—Matches any single character not in the string you specify as a 
parameter. 

• REMAIN—Matches any string starting at the current character position 
and continuing to the end of the current line. 

• SCAN—Matches the longest string of characters that does not contain any 
of the characters included in the parameter string. 

• SCANL—Same as above, except that SCANL crosses record boundaries. 

• SPAN—Matches the longest string of characters that contains only 
characters of the parameter string. 

• SPANL—Same as above, except that SPANL crosses record boundaries. 

Although the built-in procedure ANCHOR does not return a pattern data 

type, it is also used in pattern matching. It disables a seek search or 

incremental seek search and ties the search to the current character position. 

Section 4 describes each of the built-in procedures and includes a sample 

statement using the built-in procedure. 


2.8.2 Pattern Operators 

The following are the VAXTPU pattern operators: 

• Alternation operator (I) 

• Concatenation operator (&) 

• Partial pattern assignment operator (@) 

The pattern operators have equal precedence. The following sections discuss 
each of the pattern operators. 


2.8.2.1 Pattern Alternation 

The alternation operator signifies that any of the elements separated by 
this operator (I) cause a match of a pattern created by alternation. In the 
following example, if the current character is a, or b, or c, patl matches that 
character: 

patl := Ca' I 'b' I 'c') 
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2.8.2.2 Pattern Concatenation 

The concatenation operator signifies that all of the elements connected with 
this operator (&) must be present, in the order specified, for a match of a 
pattern created by concatenation. In the following example, the string 'abc' 
matches pat2: 

pat2 :« (•«' * 'b' t 'c') 

See Section 2.8.5 on pattern variables for a description of how to combine 
patterns with the concatenation operator. 


2.8.2.3 Partial Pattern Assignment 

The partial pattern operator creates a range that holds characters of a pattern 
that are already successfully matched. Use the partial pattern operator (@) 
directly in front of a variable to identify the matching range. 

Consider the following example: 

pats := ANY ('abc') Owhatchar ft 'd' 

After pats is used in a search operation, the variable whatchar contains a 
range of characters that match the preceding ANY pattern. The pattern is a 
match if both of the following conditions are true: 

1 The next character position in the string searched holds the character d. 

2 Whatchar holds a matching character from the previous expression. 

Often an entire character sequence forms the pattern for a search operation. 
However, you may only want a substring of the character sequence in the 
range returned by the built-in procedure SEARCH. If so, use the partial 
pattern assignment operator ((^) to assign ranges to parts of the pattern. The 
following example shows how to use partial pattern assignment to save the 
elements already matched in the variable number: 

! find next local B}n>>bol definition 
patl :• SPAN ('0123466789') Snunber ft 

This pattern matches strings such as '12$:'. Because only the number is of 
interest, @number causes the elements matched so far to be stored in the 
range that is represented by the variable number. 

If you need a string containing the characters matched, convert a range to a 
string as in the following example: 

numbar.string :• SUBSTR (number, 1, LENGTH (number)); 


2.8.3 Pattern Compilation and Execution 

When you compile a pattern expression, VAXTPU builds the run-time 
representation of the pattern. When you execute the pattern assignment 
statement, VAXTPU assigns the pattern data type to the variable on the 
left-hand side of the assignment statement. 

The following example shows the pattern that is assigned to the variable patl 
at execution time: 

patl LINE_END ft 'ENDIF' lend of line followed by ENDIF 
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When you compile and execute a pattern statement, the variable that 
represents the pattern can be used as a parameter for the built-in procedure 
SEARCH. A search begins at the current character position. If the search is 
successful, SEARCH returns a range. The built-in procedure SEARCH does 
not move the current character position to the matching range. If you want 
to move to the character position at which the match begins, use the range 
returned by the built-in procedure SEARCH as the parameter for the built-in 
procedure POSITION. The following example shows how to move to the 
beginning of a match: 

found_rattg« :> SEARCH (patl, FORWARD, EXACT); 

POSITION (lound_reuige); 


2.8.4 Modes of Searching 

VAXTPU has two ways to search for patterns: 

• Seek search pattern matching 

• Incremental search pattern matching 

A seek search differs from an incremental search in how the search evaluates 
the parts of a pattern formed with the alternation operator. The following 
sections discuss these two modes of pattern searching. 

You can use a seek search (the default search method), or you can force an 
incremental search. Either way, the search continues until the entire pattern 
is matched or until an end-of-search condition is met. The search begins at 
the current character position. If a match is not found, and if the direction of 
the SEARCH built-in procedure is FORWARD, the current character position 
is incremented by one. If a match is not found, and if the direction of the 
SEARCH built-in procedure is REVERSE, the current character position is 
decremented by one. 

If you do not want a search to move through the buffer, you can use the built- 
in procedure ANCHOR to tie the search to the current character. To anchor 
a search for a pattern, use the built-in procedure ANCHOR at the beginning 
of the pattern expression. For example, use the pattern x := ANCHOR 
& ('a'I'b'I'c') &'d' as the parameter for the built-in procedure SEARCH. 
VAXTPU checks for the occurrence of ad at the current character position. If 
it does not find ad, it checks for the occurrence of bd at the current character 
position. If VAXTPU does not find bd, it checks for the occurrence of cd at 
the current character position. If it does not find any of these combinations 
starting at the current character position, the search fails. 

The next two sections describe how the same search is done with a seek 
search and with an incremental search. 
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2.8.4.1 Seek Search Pattern Matching 

Seek search is VAXTPU's default mode of pattern matching with the built-in 
procedure SEARCH. Seek search is efficient in searching through a large 
number of characters. Rather than searching for a whole alternation pattern 
at each position, a seek search checks only for the first item in the alternation 
pattern at the current position. If no match is found for the first item in the 
alternation pattern, the current position is incremented by one. VAXTPU 
then checks again for the first item in the alternation pattern. When a match 
is found for the first item, VAXTPU checks for the remaining parts of the 
pattern. At times there is no match for both the first item of the alternation 
pattern and the remaining parts of the pattern. In such cases, VAXTPU 
returns to the original position and begins checking for the next part of the 
alternation pattern, and so on. 

When the pattern x := ('a'l'b'l'c') &'d' is used as a parameter for the built-in 
procedure SEARCH, VAXTPU checks for the first occurrence of ad in the 
buffer. If no match is found, VAXTPU checks for the first occurrence of bd in 
the buffer. If no match is found, VAXTPU checks for the first occurrence of 
cd in the buffer. The first match in the string 'cd bd ad' is ad even though cd 
and bd precede ad. If this is not the type of match you want, you can force 
VAXTPU to do an incremental search. (See the following section.) 

The seek search method differs from the pattern matching capabilities of other 
languages. SNOBOL, for example, searches for the whole alternation pattern 
at the current character position and then moves to the next 
character position. 


2.8.4.2 Incremental Search Pattern Matching 

With incremental search pattern matching, VAXTPU checks for a whole 
alternation pattern at the current character position. If no match is found, 
the current character position is incremented by one. The whole alternation 
pattern is then searched until a match is found, or until an end-of-search 
condition is met. 

To change VAXTPU from the default mode seek search, use the concatenation 
operator (&) immediately before an alternation pattern. One way to do this is 
to put a null string followed by the ampersand before the alternation pattern. 

When you use the pattern x := " & ('a'l'b'l'c') &'d' as the parameter for 
the built-in procedure SEARCH, VAXTPU uses incremental search pattern 
matching for the search operation. VAXTPU examines the current character 
position for ad. If no match is found, VAXTPU checks for bd. If no match is 
found, VAXTPU checks for cd. If a match is still not found, VAXTPU moves 
to the next character position and reapplies the whole pattern. The first match 
in the string 'cd bd ad' is cd because each character in the alternation pattern 
is applied before moving on to the next search position. 

Because the number of characters in a buffer is usually quite large, when you 
search an entire buffer, an incremental search is not as efficient as a seek 
search. If you construct your patterns so that the first item does not contain 
the alternation operator (I)/ O'" if you use the built-in procedure ANY rather 
than the alternation operator as the first part of a pattern, an incremental 
search is used. 
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2.8.5 Pattern Variables 

You can use the variable to which a pattern is assigned to form a new pattern. 
In the following example, patl is part of pat2: 

patl := 'a' b 'b' b 'c*; 
pat2 ;= '123' b patl b 'daf; 

When you execute a pattern that contains a nested pattern, the execution 
of the original pattern stops when it encounters the nested pattern. The 
characters already matched are saved and the nested pattern is then executed. 
When the nested pattern is finished executing, the original pattern continues 
executing. The original pattern may continue its execution at a new character 
position as a result of the evaluation of the nested pattern. 

The following example shows a nested pattern that finds a match in the text 
string 'xxxyyylzzzABCDEF": 

patl :» 'ABC b 'DBF'; 
pat2 ;= '!' b patl; 

Patl matches the text IzzzABCDEF in the text string "xxxyyylzzzABCDEF". 

Note that the matching characters of patl do not have to be adjacent to 
the first part of patl. If you want the matching characters to be adjacent, 
use the built-in procedure ANCHOR at the beginning of patl. When you 
use ANCHOR, the pattern does not look beyond the current character for 
a match. The following nested pattern does not find a match in the text 
string "xxxyyylzzzABCDEF". However, it does find a match in the text string 
'lABCDEF". 

patl := ANCHOR b 'ABC * 'DEF' 
pat2 '!' b patl 

Pattern variables and nested patterns can be used to implement wildcard 
searches. 

Do not use pattern variables recursively within the same pattern expression. 
For example, do not create a pattern like the following: 

!Invalid pattern expression 
patl 'ABC b patl 


2.9 PROGRAM 


A program data type is a collection of VAXTPU executable statements. The 
built-in procedures COMPILE and LOOKUP_XEY can optionally return a 
program data type as a result. The following example assigns a program data 
type to the variable x: 

X := COMPILE (aaln_bu«er) 

Main—buffer must contain only VAXTPU procedure definitions and 
executable statements. All procedure definitions must come before any 
executable statements that are not included in a procedure. The procedures 
and statements are compiled and the resulting program is stored in the 
variable x. 
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2.10 PROCESS 

A process data type is a VAX/VMS subprocess. The built-in procedure 
CREATE-PROCESS returns a process data type as a result. 

VAXTPU processes have the same restrictions that VAX/VMS subprocesses 
have. Following are some of the restrictions: 

• Your system subprocess quota determines how many VAXTPU processes 
you can create. 

• Only VAX/VMS utilities that can perform I/O to a mailbox and that 
do simple reads and writes (for example, MAIL) can run in a VAXTPU 
process. Programs like FMS, EDT, PHONE, or any other process that 
takes full control of the screen do not work properly in a VAXTPU 
process. (See the built-in procedure SPAWN for information on running 
these types of programs from VAXTPU.) 

• You do not see any prompts from the utility you are using. For example, 
in MAIL, you have to be aware of the sequence of prompts for sending a 
mail message because you do not see the MAIL> prompt. 

The follov«ng example assigns a process data type to the variable x: 

X CREATE_PROCESS (main.buffer, 'MAIL') 

The first parameter specifies that the output from the subprocess is to be 
stored in main_bufifer. The string 'MAIL' is the first command sent to the 
subprocess. 

To pass subsequent commands to a subprocess, use the built-in procedure 
SEND: 

SEND ('MAIL', x) 

To pass the READ command to the MAIL Utility, enter the following 
VAXTPU command: 

SEND ('READ', x) 

The output from the READ command is stored in the buffer associated with 
the subprocess x. If the buffer associated with a subprocess is deleted, the 
subprocess is deleted as well. 


2.11 LEARN 


A learn data type is a collection of VAXTPU keystrokes. The built-in 
procedure LEARN—BEGIN causes the utility to start collecting keystrokes 
and the built-in procedure LEARN—END stops the collection of keystrokes 
and returns a learn data type as a result. The following example assigns a 
learn data type to the variable x: 

LEARN.BEGIN (EXACT) 


X ;« LEARN.END 

All keystrokes that you enter between the built-in procedures 
LEARN—BEGIN and LEARN—END are stored in the variable x. The keyword 
(EXACT) specifies that, when the learn sequence is replayed, the input for 
the built-in procedures READ—CHAR, READ—KEY, and READ—LINE will 
be the same as the input entered when the learn sequence was created. If 
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you specify NO_EXACT, a replay of the built-in procedures READ-LINE, 
READ-KEY, or READ—CHAR within a learn sequence looks for new 
input. For information on replaying a learn sequence, see the description 
of LEARN-BEGIN and LEARN-END in Section 4. 

Note: Keystrokes are not the same as characters. A collection of keystrokes is 
not a printable string. 



3 Lexical Elements of the VAXTPU Language 


3.1 Overview 


A VAXTPU program is composed of lexical elements. A lexical element may 
be an individual character, such as an arithmetic operator, or it may be a 
group of characters, such as an identifier. The basic unit of a lexical element 
is a character from the DEC Multinational Character Set. (See Appendix D for 
a complete list of the DEC Multinational Characters.) This section describes 
the following VAXTPU lexical elements: 

• Character set 

• Identifiers 

• Variables 

• Constants 

• Operators 

• Expressions 

• Reserved words 


3.2 Character Set 


The DEC Multinational Character set is an 8-bit character set with 256 
characters. Each character is assigned a decimal equivalent number. These 
numbers range from 0 to 255. The first 128 characters in the set correspond 
to the American Standard Code for Information Interchange (ASCII) character 
set. The characters from 128 to 255 are extended control characters, and 
supplemental multinational characters. The characters can be grouped into 
the following categories: 

0-31 Nonprinting characters, such as tab, line feed, carriage return, and 

bell 

32 Space 

33-64 Special characters, such as ampersand (8i), question mark (?), equal 

sign (=), and the numbers 0 through 9 

65-122 The uppercase and lowercase letters (A through Z, and a through z) 

123-126 Special characters, such as the opening brace ({) and the tilde (~) 

127 Delete 

128-159 Extended control characters 

160 Reserved 

161-191 Supplemental special graphics characters, such as the copyright sign 
(©) and the degree sign (’) 
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192-254 The supplemental multinational uppercase and lowercase letters, 
such as the Spanish N and h 

255 Reserved 


The VAXTPU compiler does not distinguish between uppercase and lowercase 
characters except when they appear as part of a quoted string. For example, 
the word EDITOR has the same meaning when written in any of the 
following ways: 

EDITOR 

EDitOR 

editor 

The following characters, however, are part of quoted strings, and therefore 
represent different values: 

'xyz' 

'XYZ' 


3.2.1 Entering Control Characters 

There are two ways to enter control characters in VAXTPU: 

1 Use the built-in procedure ASCII with the decimal value of the control 
character that you want to enter. For example, COPY-TEXT (ASCII (27)) 
causes the escape character to be entered in the current buffer. 

2 Use the special functions provided by EVE or the EDT Keypad Emulator 
to enter control characters: 

a EVE provides a quote command that is bound to CTRL/V to insert 
control characters in a buffer. Press CTRL/V followed by the key that 
you want to enter (in this case, the escape key). 

b The EDT Keypad Emulator provides the SPECINS key sequence to 
insert control characters in your buffer. (The SPECINS key sequence 
consists of steps 3 and 4 in the following list of steps.) The following 
are the four steps to enter a control character with the SPECINS key 
sequence: 

1 Press the PFl key. 

2 Enter the decimal equivalent of the special character that you want 
to insert in the buffer; in this case 27. (Use the numbers on the 
keyboard, not the ones on the keypad.) 

3 Press the PFl key. 

4 Press the 3 key on the keypad). 

To enter the escape character with the SPECINS key sequence, enter 
the following: 

fPMi m B [EEll B 

Note that you must enter the 2 key and the 7 key on the keyboard. 
However, you must enter the 3 key on the ke)q)ad. 
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f> 


fS 


n 


3.2.2 VAXTPU Symbols 

Certain s)niibols have a special meaning in VAXTPU. They can be used as 
statement delimiters (;), operators (+), or other syntactic elements. The 
VAXTPU symbols are listed in Table 3-1. In symbols composed of more than 
one character, the characters cannot be separated by spaces. 


Table 3- 

■1 VAXTPU Symbols 

Symbol 

Name 

/ 

Apostrophe 

;= 

Assignment operator 

@ 

At sign, partial pattern match 

) 

Close parenthesis, ends parameter list or expression 

0 

Comma, separates parameters 

! 

Comment delimiter 

$ 

Dollar sign 

= 

Equal sign 

> 

Greater than 

> = 

Greater than or equal 

/ 

Integer division 

« 

integer multiplication 

1 

Left square bracket, begins case label 

< 

Less than 

<= 

Less than or equal 

- 

Minus sign 

<> 

Not equal 

1 

One of, pattern alternation 

( 

Open parenthesis, begins parameter list or expression 

& 

Pattern concatenation 

+ 

Plus sign, string concatenation 

II 

Quotation mark 

] 

Right square bracket, ends case label 

0 

Semicolon, separates language statements 

- 

Underscore 


3.3 Identifiers 



In VAXTPU, identifiers are used to name programs, procedures, keywords, 
and variables. An identifier is a combination of alphabetic characters, 
digits, dollar signs, and underscores, and it must conform to the following 
restrictions: 

• An identifier cannot contain any spaces or sjmibols (except the dollar sign 
and the underscore). 

• Identifiers cannot be more than 132 characters in length. 
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VAXTPU identifiers for built-in procedures, keywords, and global variables 
are reserved words. Reserved words appear in uppercase letters in this 
manual. 

You can create user-defined identifiers to name programs, procedures, and 
variables. 


3.4 Variables 


Variables are names given to VAXTPU storage locations that hold values. A 
variable name can be any valid VAXTPU identifier that is not a VAXTPU 
reserved word or the name of a user-defined procedure. You assign a value 
to a variable by using a valid identifier as the left-hand side of an assignment 
statement. Following is an example of a variable assignment: 

new.buller := CREATE.BUFFER ("new_bulfer_n«uiie") 

We suggest that you establish some convention for naming variables, so that 
you can distinguish your variables from the variables in the section file that 
you are using. 

VAXTPU allows two kinds of variables: global and local. Global variables 
are in effect throughout a VAXTPU environment. Local variables restrict the 
evaluation of a variable's value to the procedure in which it is declared. If 
you do not use the LOCAL statement to declare a variable as a local variable, 
it is implicitly considered to be a global variable. There is no explicit way of 
declaring global variables. 

Example 3-1 shows a procedure that contains a local variable declaration: 






Example 3-1 Procedure with a Local Variable 


! Tab key procedure. Always inserts a tab, even il current mode 
! Is overstrike. 


PROCEDURE user.tab 


LOCAL this.mode; 


I Local variable lor current mode 


thia_mode ;= GET.INFO (CORRENT.BUFFER, "mode"): 
SET (INSERT. CURRENT.BUFFER); 

COPY.TEXT (ASCII (9)); 

SET (thl8_mode. CURRENT.BUFFER); 


ISave current mode 
!Set node to Insert 
!Insert tab 
!Reset original mode 


ENDPROCEDURE 


The local variable this—mode has the value established in the procedure 
user—tab only when this procedure is executing. You can use this same 
variable in another procedure and assign a dififerent local value to it. You 
should not use this—mode as a global variable, because it has a special 
meaning in the procedure user—tab. 


3.5 Constants 


VAXTPU has two types of constants: integer constants and string constants. 

Integer constants can be one digit or a continuous series of digits. 

String constants can be one character or a combination of characters delimited 
by apostrophes or quotation marks. See Section 2.3 for a complete description 
of how to quote strings in VAXTPU. 
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Operators 

VAXTPU uses commonly known symbols and characters as language 
operators. There are four types of operators: 

• Arithmetic 

• Relational 

• Pattern 

• Logical 

Table 3-2 lists the symbols and language elements that VAXTPU uses as 
operators: 

Table 3-2 VAXTPU Operators 


Type 

Symbol 

Description 

Integer 

+ 

Addition, string concatenation, unary plus 

Arithmetic 

- 

Subtraction, unary minus 


* 

Multiplication 


/ 

Division 

Relational 

<> 

Not equal to 


= 

Equal to 


< 

Less than 


<= 

Less than or equal to 


> 

Greater than 


> = 

Greater than or equal to 

Pattern 

1 

& 

One of, pattern alternation 

Pattern concatenation 


@ 

Partial pattern assignment 

Logical 

NOT 

Boolean negation 


AND 

Boolean and 


OR 

Boolean or 


The precedence of the operators in an expression determines the order in 
which the operands are evaluated. Table 3-3 lists the order of precedence for 
VAXTPU operators. 
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Table 3-3 Operator Precedence 


Operator 

Precedence 

NOT 

Highest 

•, /, AND 

&, +, -, 1, OR, unary +, unary - 

<> , <, <-,>,>- 

Lowest 


Operators of equal precedence are evaluated from left to right. 

Expressions enclosed in parentheses are evaluated first. You must use 
parentheses for correct evaluation of an expression that combines relational 
operators. You must also use parentheses to ensure that expressions that 
contain unary + or unary - are evaluated correctly. For example, to add +5 
and -7, you must use the following syntax: 

6 + (-7) 

You can use parentheses in an expression to force a particular order for 
combining operands. For example: 

Expression Result 

8»6/2-4 16 

8 ♦ 6 / (2 - 4) -20 


3.7 Expressions 

An expression can be a constant, a variable, a procedure, or a combination of 
these items separated by operators. Expressions can be used in a VAXTPU 
procedure where an identifier or constant is required (except with patterns). 
Expressions are frequently used within VAXTPU conditional language 
statements. (See Section 3.8.I.4.) 

The data types of each of the elements of a VAXTPU expression must be the 
same (patterns, and the relational operators < > and = are exceptions to 
this rule). In the following example, the elements (J > 4) and (my_string = 
'this is my string') each evaluate to an integer type (integer 1 is true; integer 0 
is false) so that they can be used following the VAXTPU IF statement: 

IF (J > 4) AND (my.strittg • 'this Is my string') 

THEN 


ENDIF; 

The data types of all of the elements of a VAXTPU expression must evaluate 
to the same data type. VAXTPU does not perform implicit type conversions 
to allow for the mixing of data types within an expression. If you mix data 
types, VAXTPU issues an error message. 

With the exception of patterns, the result of an expression is the same data 
type as the elements that make up the expression. The following example 
shows a pattern expression that uses a string data t)qje on the right-hand side 
(RHS) of the expression. The pattern built-in procedures LINE_BEGIN and 
REMAIN are used with the string constant 'the' to create a pattern data type 
that is stored in the variable path 

patl ;= LINE.BEGIN A 'the' A REMAIN 
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There are four types of VAXTPU expressions: 

• Arithmetic 

• Relational 

• Boolean 

• Pattern 

The following sections discuss each of these expression types. 


3.7.1 Arithmetic Expressions 

You can use any of the arithmetic operators (+, *, /) with integer data types 

to form arithmetic expressions. VAXTPU performs only integer arithmetic. 
(The plus sign can also be used to concatenate strings.) The following are 
examples of valid VAXTPU expressions: 

12 4 ladds two integers 

•abc' + 'def !concatenates two strings 

The following is not a valid VAXTPU expression because it mixes data types: 

'abc' 12 !you cannot nix data types 

When performing integer division, VAXTPU truncates the remainder, it does 
not round. The following examples show the results of division operations: 

Expression Result 

39/10 3 

-39 / 10 -3 


3.7.2 Relational Expressions 

A relational expression tests the relationship between items of the same data 
type and returns an integer result. If the relationship is true, the result is 
integer 1; if the relationship is false, the result is integer 0. 

Use the following relational operators with any of the VAXTPU data types: 

<> 


Use the following relational operators for comparisons of integers or markers: 

> 

< 

> = 

<= 

When used with markers, these operators compare the position of the marker 
relative to the beginning of the buffer in which they are located. 
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3.7.3 Boolean Expressions 

A Boolean expression returns a true or false result. VAXTPU expresses true 
by returning the integer 1 and false by returning the integer 0. Use the logical 
operators (AND, OR, NOT) to combine one or more expressions. All parts of 
a Boolean expression are evaluated. VAXTPU evaluates expressions enclosed 
in parentheses before other elements. The following example shows the use 
of parentheses to ensure that the Boolean expression is evaluated correctly: 

IF (x « 12) AND (y <> 40) 

THEN 


ENDIF; 


3.7.4 Pattern Expressions 

A pattern expression consists of the pattern operators (@, &, I) combined 
with string constants, string variables, pattern variables, pattern procedures, 
or parentheses. The following are valid pattern expressions: 

patl ;> LINE_BEGIN k SPAN ('0123466789') A ANY ('abc'); 

pat2 LINE_END k ('end'I'begin'); 

pat3 := SCAN (';"!') k (NOTANY (•"') k LINE_END); 


3.8 Reserved Words 

Reserved words are words that are defined by VAXTPU and they have 
a special meaning for the compiler. VAXTPU reserved words appear in 
uppercase letters in this manual. Reserved words cannot be redefined by the 
user. VAXTPU reserved words can be divided into the following categories: 

• Language statements 

• Built-in procedure names 

• Keywords 

• Global variables 

The following sections describe these categories of reserved words. 








3.8.1 Language Statements 

A VAXTPU program consists of a sequence of statements. VAXTPU language 
statements control the actions performed in a procedure or a program. The 
following reserved words are language statements. 
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The Procedure Statement 
PROCEDURE ENDPROCEDURE 

The Repetitive Statement 
LOOP EXITIF ENDLOOP 

The Conditional Statement 
IF THEN ELSE ENDIF 
The Caae Statement 

CASE FROM TO INRANGE OUTRANGE ENDCASE 

The Error Statement 
ON.ERROR ENDON.ERROR 
Miscellaneous Statements 
ABORT BREAK LOCAL RETURN 

Each of these language statements is described in the following sections. 


3.8.1.1 The Procedure Statement 

The PROCEDURE—ENDPROCEDURE statements delimit a series of 
VAXTPU statements so that they are executed sequentially as though they 
were a single statement. The PROCEDURE—ENDPROCEDURE combination 
allows you to name a procedure so that you can call it from another procedure 
or from the command line of a VAXTPU editing interface. Once you have 
compiled a procedure, enter the procedure name as a statement in another 
procedure, or enter the procedure name after the TPU Command: prompt on 
the command line of EVE or the EDT Keypad Emulator. 

Syntax 

PROCEDURE procedure-name H (parameter-list) I 
ULOCAL local-variable-listU 
[[0N_ERR0R . . . END0N.ERR0R1] 
statement-1; 
statement-2; 


statement-n; 

ENDPROCEDURE 

The body of a procedure can include any VAXTPU language statements 
except the following: 

• LOCAL statements (They must precede ON—ERROR statements.) 

• ON_ERROR statements (They must precede the body of the procedure.) 

• PROCEDURE statements (A procedure can call another procedure, but it 
cannot include the procedure itself.) 

Statements that make up the body of a procedure must be separated with 
semicolons. 

Example 

PROCEDURE version 

MESSAGE ("This is Version 1-020”); 

ENDPROCEDURE 

This procedure writes the text "This is Version 1-020" in the message area. 
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3.8.1.1.1 


3.8.1.1.2 




Procedure Names 

A procedure name can be any valid identifier that is not a VAXTPU reserved 
word. We suggest that you use a convention when naming your procedures. 
For instance, you might prefix procedure names with your initials. In this 
way, you can easily distinguish procedures that you write from other 
procedures such as the VAXTPU built-in procedures. For example, if John 
Smith writes a procedure that creates two windows, he might name his 
procedure js_two_windows. This helps ensure that his procedure name is a 
unique name. Most of the sample procedures in this manual have the prefix 
user— in front of procedure names. DIGITAL suggests that you replace the 
prefix user with your initials. 


Procedure Parameters 

Using parameters with procedures is optional. If you use parameters, they 
can be input parameters, output parameters, or both. For example: 

PROCEDURE input.output (a, b) 

a :« a + 6; 
b :• a; 

ENDPROCEDURE 

In the preceding procedure, a is an input parameter. It is also an output 
parameter because it is modified by the procedure input—output. In the same 
procedure, b is an output parameter. 

The scope of procedure parameters is limited to the procedure in which they 
are defined. The maximum number of parameters in a parameter list is 31. 
However, the maximum combined number for procedure parameters and 
local variables (see Section 3.8.1.1.5) is also 31. The more local variables that 
you use, the fewer parameters you can use. 

A procedure parameter is a placeholder or dummy identifier that is replaced 
by an actual value in the program that calls the procedure. The value that 
replaces a parameter is called an argument. Arguments can be expressions. 
There does not have to be any correlation between the names used for 
parameters and the values used for arguments. All arguments are passed by 
reference. Example 3-2 shows a simple procedure with parameters. 

Example 3-2 Simple Procedure with Parameters 






IThls procedure adds two integers. The parameters, Inti and int2, 
I are replaced by the actual values that the user supplies. 

!The result of the addition is written to the message area. 

PROCEDURE add (inti, int2) 

MESSAGE (STR (inti * int2)); 

ENDPROCEDURE 


For example, call the procedure ADD and specify the values 5 and 6 as 
arguments as follows: 

ADD (6, e) 

The integer 11 is written to the message buffer. 

Example 3-3 shows a more complex procedure that uses a parameter. 


3-10 



Lexical Elements of the VAXTPU Language 


3.8.1.1.3 


Example 3-3 Complex Procedure with Parameters 


i BLISS$BEGIN_BLANKS - begin a line with blanks 
! 

I Bind this procedure to the return key 
PROCEDURE BLISS|BEGIN_BLANKS (start.loop.count) 

LOCAL loop.count; 

SPLIT_LINE; 

!The user provides this value as a paraneter 
{following the procedure name, 
loop.count start.loop.count; 

!♦ 

{Start line with TABs, until within 8 columns of target 

j. 

LOOP 

EXITIF loop.count < 8; 

COPy.TEXT (ASCII (9)): 
loop.count ;• loop.count - 8; 

ENDLOOP; 

! + 

{Add spaces until target column Is reached 

I. 

LOOP; 

EXITIF loop.count >■ 0; 

COPY.TEXTC •); 
loop.count := loop.count - 1; 

ENDLOOP; 

ENDPROCEDURE 


Procedures That Return a Result 

Procedures that return a result are called function procedures. Example 3-4 
shows a procedure that returns a true (integer 1) or false (integer 0) value. 

Example 3-4 Procedure That Returns a Result 


PROCEDURE usar.on.and.of.llne {test If at eol, return true or false 
IF CURRENT.OFFSET - LENGTH (CURRENT.LINE) {we are on eol 

THEN 

user.on_end_of_llne 1 {return true 

ELSE 

user.on_end.of_llne :■ 0 {return false 

ENDIF; 

ENDPROCEDURE 


Another way of assigning a value of 1 or 0 to a procedure is to use 
the VAXTPU language statement RETURN followed by a value. See 
Example 3-12. 

You can use a procedure that returns a result as a part of a conditional 
statement to test for certain conditions. Example 3-5 shows the procedure in 
Example 3-4 within another procedure. 
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Example 3-5 Procedure Within Another Procedure 


PROCEDURE 


IF 

user_on.«nd_ol_line • 1 !at the eol mark 

THEN 

MESSAGE ("Cursor is at the end of the line”) 

ELSE 

MESSAGE ("Cursor is not at the end of the line”) 

ENDIF; 


ENDPROCEDURE 


3.8.1.1.4 Recursive Procedures 

Procedures that call themselves are called recursive procedures. Example 3-6 
shows a procedure named user_reverse that displays a list of responses to the 
built-in procedure READ-LINE in reverse order. Notice that there is a call to 
the procedure user-reverse within the procedure body. 

Example 3-6 Recursive Procedure 


PROCEDURE user.reverse 
LOCAL temp.string; 


temp.string READ_LINE(*input>” 
IF temp.string <> " " 

THEN user.reverse 
ELSE RETURN 
ENDIF; 

MESSAGE (temp.string); 
ENDPROCEDURE 


!Read a response 

{Quit if nothing entered but the 
iCall user.reverse recursively 
!A11 done, go to display lines 

! Display lines typed in reverse 
! in the message window 


RETURN key 


order 


3.8.1.1.5 Local Variables 

The use of local variables in procedures is optional. If you use local variables, 
they hold the value that you assign them only in the procedure in which 
you declare them. The maximum number of local variables that you can 
use is 31. However, the maximum combined number for local variables 
and procedure parameters (see Section 3.8.1.1.2) is also 31. The number of 
procedure parameters that you use lowers the number of local variables that 
you can use. 

The syntax for a local-variable list is as follows: 

LOCAL variable name 


3.8.1.1.6 Error Statements 

The use of ON—ERROR statements in procedures is optional. If you use 
an ON—ERROR statement, you must place it at the top of the procedure 
just after the LOCAL statement, if present. The ON—ERROR statement 
specifies the action or actions to be taken if an ERROR or WARNING 
status is returned. See Section 3.8.1.6 for more information on ON—ERROR 
statements. 
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3.8.1.2 The Assignment Statement 

The assignment statement assigns a value to a variable. In so doing, it 
associates the variable with the appropriate data type. 

Syntax 

Idsntlfier :• expression 

Note that the assignment operator is a combination of two symbols, a colon 
and an equal sign (:=). Do not confuse this operator with the equal sign (=), 
which is a relational operator that checks for equality. 

VAXTPU does not do any type checking on the data type being stored. Any 
data type may be stored in any variable. 

Example 

X ; = 'abc' 

This assignment statement stores the string 'abc' in variable x. 


3.8.1.3 The Repetitive Statement 

The LOOP—ENDLOOP statements specify the repetitive execution of a 
statement or statements until the condition specified by EXITIF is met. 

Syntax 

LOOP 

atatemeot-l; 

BtateBent-2; 


EXITIF expraaslon; 
etateBant-n; 

ENDLOOP 

The EXITIF statement is the mechanism for exiting from a loop. (An error 
statement can cause an implicit exit from a loop if a statement within the 
loop causes an error condition to occur.) You can place the EXITIF statement 
anywhere inside a LOOP—ENDLOOP combination. You can also use the 
EXITIF statement as many times as you like. When true, the EXITIF statement 
causes a branch to the statement following the ENDLOOP statement. 

The syntax of the EXITIF statement is as follows: 

EXITIF axpraBalon 

Any VAXTPU language statement can appear inside of a LOOP—ENDLOOP 
combination except PROCEDURE, LOCAL, and ON—ERROR statements. 

You can nest LOOP—ENDLOOP statements to a depth of 20. 

Example 

LOOP 

EXITIF CURRENT.OFFSET » 0; 
tBBp.strlng ;■ CURRENT.CHARACTER; 

EXITIF (teBp.Btring <> ” *) and 
(tBBp.strlng <> ascii (9)); 

M0VE_H0KIZ0NTAL (-1); 
tsBp.length tsBp.length 1; 

ENDLOOP 
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This procedure uses the EXITIF statement twice. Each expression following 
an EXITIF statement defines conditions that cause an exit from the loop. The 
statements in the loop are repeated until one of the EXITIF conditions is met. 


3.8.1.4 The Conditional Statement 

The IF—THEN statement causes the execution of a statement or group of 
statements, depending on the value of a Boolean expression. If the expression 
is true, the statement is executed. Othervdse, program control passes to the 
statement following the IF—THEN statement. 

The optional ELSE clause provides a group of alternative statements for 
execution. The ELSE clause is executed if the test condition specified by 
IF—THEN is false. 

The ENDIF statement sjTecifies the end of a conditional statement. 

Syntax 

IF expression 

THEN statement-1; 


statement-n; 

HELSE altemate-statement-1; 


altemate-statement-n; ]] 

ENDIF 

You can use any VAXTPU language statements in a THEN or ELSE clause 
except PROCEDURE, LOCAL, and ON—ERROR statements. 

You can nest conditional statements to a depth of 20. 

Example 

PROCEDURE set.dlrect 

MESSAGE ('Press PF3 or PF4 to Indicate direction'); 
temp.char READ.KEY; 

IF temp.char ■ KPS 

THEN SET (REVERSE. CORRENT.BUFFER); 

ELSE 

IF temp.char = KP4 

THEN SET (FORWARD, CORRENT.BUFFER); 

ENDIF; 

ENDIF 

ENDPROCEDURE 

In this example, nested IF—THEN—ELSE statements test whether a buffer 
direction should be FORWARD or REVERSE. 


3.8.1.5 The Case Statement 

The CASE statement is a selection control structure that allows you to list 
several alternate actions and choose one of them to be executed at run time. 
In a CASE statement, constant values, or case labels, are associated with 
the possible executable statements or actions to be performed. The CASE 
statement then executes the statement or statements labeled with a value that 
matches the value of the case-selector. 
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Syntax 

CASE case-aelector FROM case-lower-constant TO cass-upper-constant 
[case-constant-1 I,...]]] : statement [[,...1: 
[case-constant-2 ; statement 


[case-constant-n I,...]]] : statement H....]]; 

([[INRANGE] ; statement D!....!);! 

[[[OOTRANGE] : statement I,...I;I 

ENDCASE 

Note: The single square brackets are not optional for case constants. 

Example 3-7 shows how to use the CASE statement in a procedure. 

CASE constants can be keywords, string constants of one character in length, 
or integer constants. There are two special case constants in VAXTPU: 
INRANGE and OUTRANGE. INRANGE matches anything that falls within 
the case range that does not have a case label associated with it. OUTRANGE 
matches anything that falls outside the case range. These special case 
constants are optional. 

CASE statements can be nested to a depth of 20. Example 3-7 shows a 
sample procedure that uses the CASE statement. 


Example 3-7 Procedure Using the CASE Statement 


PROCEDURE grades 

answers ;= READ.LINE ('Enter number ol correct answers:',5}; 
answers INT (answers); 

CASE answers FROM 0 TO 10 


[10] 

score 


■A+'; 

[9] 

score 

: = 

■A'; 

[8] 

score 

: = 

'B'; 

[7] 

score 

: = 

■C; 

[6] 

score 

; = 

•D': 

[0.1,2.3.4,6] 

score 

:* 

■F': 

[OUTRANGE] 

score 

: = 

'Invalid entry 


ENDCASE; 

MESSAGE (score): 
EHDPROCEDURE 


This CASE statement compares the value of the constant-selector answers to 
the case labels (the numbers 0 through 10). If the value of answers is any of 
the numbers from 0 through 10, the statement to the right of that number is 
executed. If the value of answers is outside the range of 0 through 10, the 
statement to the right of [OUTRANGE] is executed. The value of score is 
written in the message area after the execution of the CASE statement. 
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3.8.1.6 The Error Statement 

The ON—ERROR—ENDON—ERROR statements delimit the actions that 
are to be taken when a procedure fails to execute successfully. The 
ON—ERROR—ENDON JRROR combination is an optional part of a 
VAXTPU procedure. The ON_ERROR—ENDON-ERROR statements 
trap WARNING and ERROR status values. (See Section 4, SET 
(INFORMATIONAL ... ) and SET (SUCCESS . .. ) for information on 
handling INFORMATIONAL and SUCCESS status values.) 

If a WARNING status is trapped by an ON—ERROR statement, the warning 
message is suppressed. However, if an ERROR status is trapped, the message 
is displayed. The ON—ERROR trap allows you to do additional error 
handling after the VAXTPU message is displayed. 

Syntax 

0N_ERR0R 

statement-l; 

8tateEient-2; 


atatenant-n; 

ENDON.mOR 

ON—ERROR language statements must be placed at the beginning of a 
procedure; after the procedure-parameter list or the local-variable list, 
if present, and before the body of the procedure. Error statements can 
contain any VAXTPU language statements except PROCEDURE, LOCAL, and 
ON—ERROR statements. 

There are two reserved VAXTPU global variables that can be included in 
an ON—ERROR—ENDON—ERROR statement: ERROR—LINE and ERROR. 
VAXTPU assigns a value to these two variables when a procedure returns an 
error or a warning status. ERROR—LINE contains the line number at which 
the error or warning occurs. If a procedure was compiled from a buffer or 
range, ERROR—LINE contains the line number within the buffer. (This may 
be different from the line number within the procedure.) If the procedure was 
compiled from a string, ERROR—LINE contains 1. 

ERROR contains a keyword for the error or warning. The possible error 
and warning statuses that can be returned by each built-in procedure are 
included in the description of each built-in procedure in Section 4. (Appendix 
C contains an alphabetized list of all the possible return statuses for VAXTPU 
and their severity levels. The VAX/VMS System Messages and Recovery 
Procedures Reference Manual includes all the possible return statuses for 
VAXTPU as well as the appropriate explanations and suggested user actions.) 

After the execution of an error statement, you can choose where to resume 
execution of a program. The options are the following: 

• ABORT—This language statement causes an exit from the interpreter. 

• RETURN—This language statement stops the execution of the procedure 
in which the error occurred, but continues execution of the rest of the 
program. 

If you do not specify ABORT or RETURN, the default is to continue executing 
the program from the point at which the error occurred. 
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Example 3-8 shows error statements at the beginning of a procedure. These 
statements return control to the caller if the input on the command line of an 
interface is not correct. Any warning or error status returned by a statement 
in the body of the procedure causes the error statements to be executed. 

Example 3-8 Procedure Using the ON_ERROR Statement 


!♦ 

I gold 7 OHulation (coaaand line procesBlng) 

I. 

PROCEDURE command.lin* 

LOCAL 

llne.read, x; 

ON.ERROR 

MESSAGE CUnrecognizod command: ' + llne.read); 

RETURN; 

ENDON.ERROR 
! + 

! Get the conaand(s) to execute 

I. 

llne.read :* READ.LINE CTPU Command: '); ! get line from user 
!♦ 

! compile them 
!- 

IF llne.read <> ■' 

THEN X :> COMPILE (llne.read); 

ELSE RETURN 
ENDIF; 

! + 

! execute 
!- 

IF X <> 0 

THEN EXECUTE (x); 

ENDIF; 

ENDPROCEDURE 


3.8.1.7 Miscellaneous Statements 

This section describes the four VAXTPU language statements ABORT, BREAK, 
LOCAL, and RETURN. 


3.8.1.7.1 ABORT 

The ABORT statement causes an exit from the interpreter and a return to the 
main control loop of VAXTPU (interactive key processing). Using the ABORT 
statement is analogous to pressing CTRL/C at the DCL level. ABORT can be 
included in the ON—ERROR statements at the beginning of a procedure to 
cause an exit from nested procedures, rather than a return to an intermediate 
procedure. 

Include the ABORT statement only in procedures that you use interactively. 

If you include an ABORT statement in a VAXTPU procedure that is executed 
in batch mode, VAXTPU attempts to open SYS$INPUT to read keystrokes. 
This causes the editor to abort, because VAXTPU cannot read keystrokes from 
a DCL conunand procedure. 
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3.8.1.7.2 BREAK 

The BREAK statement is used to set a breakpoint for debugging purposes. 
After checking for a certain condition with an IF—THEN statement, you can 
use BREAK to cause a breakpoint that does one of the following: 

• Invokes a user-written debugger (See SET (DEBUG, .. . ) in Section 4.) 

• Causes the following message to be written to the message buffer: 

"BREAK at line (line nunber at which the BREAK occurred)" 

Syntax 

BREAK 

The predefined VAXTPU global variable DEBUG-LINE can be used in user- 
written debuggers. DEBUG_LINE contains the line number on which a 
breakpoint occurred. 

Example 3-9 is a procedure that causes a breakpoint if the expression 
following the IF statement is true. 

Example 3-9 Procedure Using the BREAK Statement 


PROCEDURE one 


IF expression 
THEN BREAK; 
ENDIF; 


ENDPROCEDURE 


See Section 5 for information on debugging VAXTPU programs. 


3.8.1.7.3 LOCAL 

This statement is used to identify certain variables as local variables rather 
than global variables. All variables are considered to be global variables 
unless you explicitly use the LOCAL statement to identify them as local 
variables. The LOCZAL statement must be used immediately after the 
PROCEDURE statement. 

Syntax 

PROCEDURE procedure.nams 
LOCAL 

variable d ,... I]; 
statement.!; 


statement.n; 

ENDPROCEDURE 
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3.8.1.7.4 


RETURN 

This statement causes a return to the procedure that called the current 
procedure. The return is to the statement following the statement that called 
the current procedure. 

The RETURN statement is often used in the ON—ERROR section of a 
procedure to specify a return to the calling procedure if an error occurs in 
the current procedure. Example 3-10, an adapted version of a procedure from 
EVESECINI.TPU, uses the RETURN statement in an ON—ERROR section. 

Example 3-10 Using RETURN in an ON_ERROR Section 


I Attach back to the parent process. Used when Eve is spawned 
! from DCL and run in a subprocess ("kept VAXTPU"). The 
! ATTACH command can be used for more flexible process control. 

PROCEDURE eve.attach 
0N_ERR0R 

IF ERROR - TPU$_N0PARENT 

THEN MESSAGE ("Not running VAXTPU in a subprocess"); 
RETURN; 

ENDIF; 

END0N_ERR0R; 

ATTACH; 

ENDPROCEDURE; 


You can specify a value after the RETURN statement and this value is passed 
to the calling procedure. Example 3-11 shows a sample procedure in which a 
value is returned to the calling procedure. 

Example 3-11 Procedure Returning a Value 


PROCEDURE ussr_gst_shlft_ksy 

LOCAL ksy.to.shlft; ! Keyword for key pressed after shift key 

SET (SHIFT.KEY, LAST.KEY); 

key_to_shift KEY.NAME (READ.KEY, SHIFT.KEY); 

RETURN (key.to.shift); 

ENDPROCEDURE; 


In addition to using RETURN to pass a value, you can use a 1 (true) or a 
0 (false) with the RETURN statement to indicate the status of a procedure. 
Example 3-12 shows this usage of the RETURN statement. 

Example 3-12 Procedure Returning a Status 


PROCEDURE user_at_end_of_line 

IThls procedure returns a 1 (true) if user is at the end of a line, 
lor a 0 (false) if the current character is not at the end of a line 
ON.ERROR 

! Suppress warning message 
RETURN (1); 

END0N_ERR0R; 

IF CURRENT.OFFSET * LENGTH (CURRENT.LINE) 

THEN 

RETURN (1) 

ELSE 

RETURN (0) 

ENDIF; 

ENDPROCEDURE; 
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The following sections list other VAXTPU reserved words. 


3.8.2 Built-In Procedure Names 

The names of the built-in procedures listed in Table 3-4 are reserved for use 
by VAXTPU. 


Table 3-4 VAXTPU Built-In Procedures 


ADD_KEY_MAP 

ERASE 

QUIT 

ADJUST_WIND0W 

ERASE-CHARACTER 

READ-CHAR 

ANCHOR 

ERASE-LINE 

READ-FILE 

ANY 

EXECUTE 

READ-KEY 

APPEND_LINE 

EXIT 

READ-LINE 

ARB 

EXPAND-NAME 

REFRESH 

ASCII 

FAO 

REMOVE-KEY-MAP 

ATTACH 

FILE-PARSE 

REMAIN 

BEGINNING_OF 

FILE-SEARCH 

SAVE 

CALL-USER 

FILL 

SCAN 

CHANGE-CASE 

GET-INFO 

SCANL 

COMPILE 

HELP-TEXT 

SCROLL 

COPY-TEXT 

INDEX 

SEARCH 

CREATE-BUFFER 

INT 

SELECT 

CREATE-KEY-MAP 

JOURNAL-CLOSE 

SELECT-RANGE 

CREATE-KEY-MAP-LIST 

JOURNAL-OPEN 

SEND 

CREATE-PROCESS 

KEY-NAME 

SEND-EOF 

CREATE-RANGE 

LAST-KEY 

SET 

CREATE-WINDOW 

LEARN-BEGIN 

SHIFT 

CURRENT-BUFFER 

LEARN-END 

SHOW 

CURRENT-CHARACTER 

LENGTH 

SPAN 

CURRENT-COLUMN 

LINE-BEGIN 

SPANL 

CURRENT-DIRECTION 

LINE-END 

SPAWN 

CURRENT-LINE 

LOOKUP-KEY 

SPLIT-LINE 

CURRENT-OFFSET 

MAP 

STR 

CURRENT-ROW 

MARK 

SUBSTR 

CURRENT-WINDOW 

MATCH 

TRANSLATE 

CURSOR -HORIZONTAL 

MESSAGE 

UNDEFINE-KEY 

CURSOR-VERTICAL 

MOVE-HORIZONTAL 

UNMAP 

DEFINE-KEY 

MOVE-TEXT 

UPDATE 

DELETE 

MOVE-VERTICAL 

WRITE-FILE 

EDIT 

NOTANY 


END_OF 

POSITION 
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3.8.3 



Keywords 


Keywords have a special meaning for the VAXTPU compiler and are reserved 
for use by VAXTPU. Keywords are used in the following ways: 

• As parameters for VAXTPU built-in procedures (ALL, BLINK, PF2, . . . ). 
The first parameter following the built-in procedure SET is always a 
keyword (PAD, SCROLLING, STATUS-LINE, ... ). 

• As values returned by GET_INFO (FORWARD, GRAPHIC-TABS, 
UNDERLINE, ... ). 

• To specify the VAXTPU data types (BUFFER, MARKER, LEARN, . . . ). 

• To report WARNING or ERROR status conditions (TPU$_BADMARGINS, 

TPU$-CREATEFAIL, TPU$-NOEOBSTR_). 

VAXTPU stores keywords as predefined integer values. However, you should 
not use integer values to specify keywords. DIGITAL does not support 
keywords in that form and the integer values may not be the same in future 
versions. 

You can display an alphabetic list of all VAXTPU keywords by using the 
SHOW (KEYWORDS) command after the appropriate prompt from your 
editing interface. You can also find lists of certain keywords in the Index. 
Under the topic Keyword, there is a list of the keywords used as parameters for 
VAXTPU built-in procedures. Some of the ke 3 rwords used to specify ERROR 
and WARNING conditions are listed in the Index under TPU$—message-id. 

Table 3-5 shows the correspondence between keywords used as VAXTPU 
keynames and the keys on the VTIOO and VT200 series of keyboards: 


Table 3-5 Keywords Used for Keynames 


VAXTPU Keynames for the Editing and Auxiliary Keypad 

VAXTPU Keyname VT200-Type VT100-Type 

PM PM PM 

PF2 PF2 PF2 

PF3 PF3 PF3 

PF4 PF4 PF4 


KPO.KPI.KP9 

PERIOD 

COMMA 

MINUS 

ENTER 

UP 

DOWN 

LEFT 

RIGHT 

El 

E2 

E3 


0,1.9 


ENTER 

up-arrow 

down-arrow 

left-arrow 

right-arrow 

FIND/E 1 

INSERT-HERE/E2 

REMOVE/E3 


0,1.9 


ENTER 

up-arrow 

down-arrow 

left-arrow 

right-arrow 
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Table 3-5 (Cont.) 

Keywords Used for Keynames 

VAXTPU Keynames for the Editing and Auxiliary Keypad 

VAXTPU Keyname 

VT200-Type 

VT100-Type 

E4 

SELECT/E4 


E5 

PREV-SCREEN/E5 


E6 

NEXT-SCREEN/E6 


HELP 

HELP/FI 5 


DO 

DO/FI 6 


F6,F7.F20 

F6,F7.F20 


VAXTPU Keynames for Keys on the Main Keyboard 


VAXTPU Keyname 

VT200-Type 

VT100-Type 

TAB-KEY 

TAB 

TAB 

RET-KEY 

RETURN 

RETURN 

DEL-KEY 

<X] 

DELETE 

LF-KEY 


line-feed 

BS-KEY 


backspace 

CTRL-A-KEY 

CTRL/A’ 

CTRL/A’ 

CTRL_B_KEY 

CTRL/B 

CTRL/B 

CTRL-Z-KEY 

CTRL/Z 

CTRL/Z 


’ CTRL/A refers to the CTRL key being pressed simultaneously with the A key. A 
and a produce the same results. 


3.8.4 VAXTPU Global Variables 

There are three reserved words that are VAXTPU global variables. Following 
are the variables and the information they hold: 

ERROR Keyword that specifies an error or warning status 

ERROR-LINE Line number at which an error or warning occurred 
DEBUG—LINE Line number at which a breakpoint occurred 

See Section 3.8.1.6 for a discussion of ERROR and ERROR-LINE. See Section 
3.8.1.7.2 for a discussion of DEBUG—LINE. 
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This section describes each of the VAXTPU built-in procedures. The section is 
divided into two subsections. Section 4.1 groups the built-in procedures 
according to the functions that they perform. Section 4.2 contains an 
alphabetic list of the built-in procedures with a detailed description of each 
procedure. 


4.1 Built-in Procedures Grouped According to Function 

When you want to perform editing tasks, use the following lists to help you 
identify which built-in procedures are related to a task. For more information 
about a built-in procedure, see its individual description in Section 4.2. 


4.1.1 Screen Layout 

• ADJUST-WINDOW 

• CREATE-WINDOW 

• MAP 

• REFRESH 

• SHIFT 

• UNMAP 

• UPDATE 


4.1.2 Cursor Movement 

• CURSOR-HORIZONTAL 

• CURSOR-VERTICAL 

• SCROLL 


4.1.3 Moving the Editing Position 

• MARK 

• MOVE-HORIZONTAL 

• MOVE-VERTICAL 

• POSITION 
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4.1.4 Text Manipulation 

• APPEND_LINE 

• BEGINNING-OF 

• CHANGE-CASE 

• COPY-TEXT 

• CREATE-BUFFER 

• CREATE-RANGE 

• EDIT 

• END-OF 

• ERASE 

• ERASE-CHARACTER 

• ERASE-LINE 

• HLE-PARSE 

• HLE-SEARCH 

• FILL 

• MOVE-TEXT 

• READ-FILE 

• SEARCH 

• SELECT 

• SELECT-RANGE 

• SPLIT-LINE 

• TRANSLATE 

• WRITE-FILE 


4.1.5 Pattern Matching 

• ANCHOR 

• ANY 

• ARB 

• LINE-BEGIN 

• LINE-END 

• MATCH 

• NOTANY 

• REMAIN 

• SCAN 

• SCANL 
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n 

4.1.6 

n 

^ 4.1.7 

o 

4.1.8 

a 


• SPAN 

• SPANL 


Status of the Editing Context 

• CURRENT-BUFFER 

• CURRENT-CHARACTER 

• CURRENT-COLUMN 

• CURRENT-DIRECTION 

• CURRENT-LINE 

• CURRENTL-OFFSET 

• CURRENT-ROW 

• CURREN'LWINDOW 

• GET-INFO 

• SET 

• SHOW 


Defining Keys 

• ADD-KEY-MAP 

• CREATE-KEY-MAP 

• CREATE-KEY-MAP-LIST 

• DEFINE-KEY 

• KEY-NAME 

• LAST-KEY 

• LOOKUP-KEY 

• REMOVE-KEY-MAP 

• UNDEHNE-KEY 


Multiple Processing 

• ATTACH 

• CREATE-PROCESS 

• SEND 

• SEND_EOF 

• SPAWN 


4-3 





VAXTPU Built-In Procedures 


4.1.9 Program Execution 

• COMPILE 

• EXECUTE 

• SAVE 


4.1.10 Miscellaneous 

• ASCII 

• CALL-USER 

• DELETE 

• EXPAND-NAME 

• EXIT 

• FAO 

• HELP-TEXT 

• INDEX 

• INT 

• JOURNAL-CLOSE 

• JOURNAL-OPEN 

• LEARN-BEGIN 

• LEARN-END 

• LENGTH 

• MESSAGE 

• QUIT 

• READ-CHAR 

• READ-KEY 

• READ-LINE 

• STR 

• SUBSTR 
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4.2 Descriptions of the Built-In Procedures 

The descriptions of the built-in procedures are divided, as applicable, into the 
following parts: 

• A short functional definition 

• Format 

• Description 

• Return Status lists the WARNINGS and ERRORS returned, if applicable 

• Examples 

The descriptions are arranged alphabetically. 
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ADD_KEY-_MAP 

Adds one or more key maps to a key-map list. 


FORMAT ADD_KEY_MAP (string 1, string2, stringSl[,...]l) 

parameters string 1 

A string that specifies the name of the key-map list. 

string2 

Either the string "first" or the string "last". This parameter specifies whether 
the key map is added to the beginning or the end of the key-map list, 
respectively. In cases where a key is defined in multiple key maps, the 
definition in the first key map in a key-map list is used. 

Strings 

A string that specifies the name of the key map to be added to the key-map 
list. You can specify more than one key map. Key maps are added to the 
key-map list in the order specified. The order of a key map in a key-map list 
determines precedence among any conflicting key definitions. 


DESCRIPTION The built-in procedure ADD_KEY_MAP adds key maps to key-map lists. Key 

maps are added, in the specified order, to either the top or the bottom of the 
key-map list. Key-map precedence in a key-map list is used to resolve any 
conflicts between key definitions. The key definition in a preceding key map 
overrides any conflicting key definitions in key maps which are subsequent 
on the key-map list. 

See the descriptions of the built-in procedures DEFINE _KEY, 

CREATE _KEY_MAP, and CREATE _KEY_MAP_LIST for more information 
on key definitions, key maps, and key-map lists, respectively. Also see the 
description of the built-in procedure REMOVE _KEY_MAP for information on 
removing key maps from a key-map list. 


TPU$_NOKEYMAP WARNING Third argument is not a defined key 

map. 

TPU$_KEYMAPNTFND WARNING The key map listed in the third 

argument is not found. 

EXAMPLES 

□ ADD_KEY_MAP ("TPU$KEY_MAP_LIST", "TPUSKEY.MAP"); 

This Statement adds the default key map, TPU$KEY_MAP, to the default 
key-map list, TPU$KEY_MAP_LIST. Normally (except in the EVE interface), 
TPU$KEY_MAP is a member of the default key map list. 
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Q SAMPLE PROCEDURE 


The following statements create a key map called help_keys and add it to 
the default key-map list, TPU$KEY_MAP_L1ST. Keys defined in the new key 
map are invoked over definitions in the key maps already in the list. 

h«lp.k«ya CREATE_KEY_MAP ("halp.kays"); 

ADD_KEY_MAP ("TPU$KEY_MAP.LIST". "first", halp.kays); 
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ADJUST_WINDOW 


Changes the size and/or screen location of a window and makes the 
window that you specify the current window. 


FORMAT ADJUST-WINDOW (window, integerl, integer2} 


parameters window 

The window whose size or location you want to change. The window that 
you specify becomes the current window. 

integerl 

The signed (+/“) integer value that you add to the screen line number at the 
top of the window. 

integer2 

The signed (+/~) integer value that you add to the screen line number at the 
bottom of the window. 


DESCRIPTION If you want to check the size and/or location of a window before making an 

adjustment to it, use any of the following statements: 

SHOW (WINDOW) 

SHOW (WINDOWS) 

top :• GET.INFO (window, "viwiblo.top"); 

MESSAGE (STR (top)); 

bottom :• GET.INFO (window, "vlslble.bottom”); 

MESSAGE (STR (bottom)); 

There are screen line numbers at both the top and the bottom of the visible 
window. Adjust the size of a visible window by changing either or both of 
these screen line numbers. Make these changes by adding to or subtracting 
from the current screen line number, not by specifying the screen line number 
itself. 

You can enlarge a window by decreasing the screen line number at the top of 
the window. (Specify a negative value for integerl.) You can also enlarge a 
window by increasing the screen line number at the bottom of the window. 
(Specify a positive value for integer2.) The following example adds four 
lines to the current window provided that the values fall within the screen 
boundaries: 

ADJUST.WINDOW ((^RRENT.WINDOW, -2. +2) 

If you specify integers that attempt to set the screen line number beyond 
the screen boundaries, VAXTPU issues a warning message. VAXTPU then 
sets the window boundary at the edge (top or bottom, as appropriate) of the 
screen. 

You can reduce a window by increasing the screen line number at the top of 
the window. (Specify a positive value for integerl.) You can also reduce a 
window by decreasing the screen line number at the bottom of the window. 
(Specify a negative value for integer2.) If you attempt to make the size of 
the window smaller than one line, VAXTPU issues an error message and no 
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adjustment occurs. The following example reduces the current window by 
four lines: 

ADJUST.WINDOW (CURREMT.WINDOW, +2, -2) 

You can also use ADJUST-WINDOW to change the position of the window 
on the screen without changing the size of the window. The following 
command simply moves the current window two lines higher on the screen 
provided that the values fall within the screen boundaries: 

ADJUST.WINMW (CORRENT.WINDOW, -2, -2) 

Figure 4-1 shows a screen layout when you invoke VAXTPU with the EDT 
Keypad Emulator section file and a user-written command file. In this case, 
the user-written command file divides the screen into two windows. The 
top window has 15 text lines (including the end-of-buffer message) and a 
status line. The bottom window has five text lines and a status line. The two 
bottom lines of the screen are the message window. This message window 
contains two messages. The first message lists the file (LINE-NUMBERS.FIL) 
that was read into the main buffer. The second message lists the command 
file (TPUINI.TPU) that was used to customize the EDT Keypad Emulator 
interface. 

Figure 4-1 Screen Layout Before Using ADJUST-WINDOW 



ZK-4047-85 


The user-written command file uses the variable second—window to identify 
the bottom window. Figure 4-2 shows the screen layout after the user enters 
ADJUST—WINDOW (second-window, -5, 0) after the appropriate prompt 
from the EDT Keypad Emulator. Both the top and bottom windows now 
contain 10 lines of text and a status line. Note that the cursor is now located 
in the bottom window. The message window still contains two lines. 
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Figure 4-2 Screen Layout After Using ADJUST-WINDOW 



ZK-4048-85 


Because the built-in procedure ADJUST-WINDOW adds (+/“) integerl to 
the "visible—top' and (+/-) integer2 to the "visible—bottom" of a window, 
it causes a window to be re-created. The new values for the screen line 
numbers become the values for "original—top' and "original—bottom". (See 
Section 2.5 for more information on window dimensions and window values.) 
When VAXTPU remaps a window, it may partially or entirely occlude other 
windows on the screen. The newly mapped window becomes the most 
recently mapped window in the VAXTPU internal list and the cursor is 
moved to this window. The current character position in the buffer becomes 
the position VAXTPU saved the last time you were in this window. Part or 
all of the window may be redisplayed or scrolled to keep the current position 
visable after the adjustment occurs. 

Note that both ADJUST—WINDOW and MAP may cause other windows to 
become partially or completely occluded or segmented. 

If you execute ADJUST—WINDOW within a procedure, the screen is not 
immediately updated to reflect the adjustment. The adjustment is made after 
the entire procedure is finished executing and control returns to the screen 
manager. If you want the screen to reflect the adjustment to the window 
before the entire procedure is executed, you can force the immediate update 
of a window by adding an UPDATE statement to the procedure. See the 
built-in procedure UPDATE for more information. 
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RETURN 

STATUS 


TPU$_WINDNOTMAPPED WARNING 

TPU$_BADWINDADJUST WARNING 
TPU$_WINDNOTVIS WARNING 


Cannot adjust a window that is 
not mapped 

Invalid adjustment length calculated 
No adjustment if window is not visible 


EXAMPLES 

□ ADJUST.WINDOW (CURRENT.WINDOW, +6, 0) 

This statement reduces the current window by removing five lines from the 
top of the window. If the top line of the window is screen line number 11, 
this statement changes the top line of the window to screen line number 
16. (If the bottom line of the window is less than screen line number 16, 
VAXWU signals an error.) 

Q SAMPLE PROCEDURE 


The following procedure removes five lines from the top of a window and 
puts a help window in their place. 

PROCEDURE us«r_dlaplay_li«lp 

top.of.window GET.INFO (CURRENT.WINDOW, "VISIBLE.TOP"); 

! 

! Remove the top live lines from the current window 
! and replace them with a help window 

j 

ADJUST.WINDOW (CURRENT.WINDOW, +6, 0); 
example.window :• CREATE.WINDOW (top.ol.window, 5, ON); 
example.bulfer :• CREATE.BUFFER ("EXAMPLE”, 

"sysllogin:template.txt"); 

MAP (example.window, example.bulfer); 

ENDPROCEDURE; 
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ANCHOR 

Disables seek search or incremental search pattern matching and 
ties a search for a matching string to the current character position. 

FORMAT 

ANCHOR 

parameters 

None. 

DESCRIPTION 

By default, when the built-in procedure SEARCH fails to find a matching 
pattern, the character position is moved one position. The search then 
continues until a match is found or until an end-of-search condition is 
reached. The character position is moved forward or backward depending on 
the direction of the built-in procedure SEARCH. The end-of-search condition 
is the end of the buffer if the direction of the search is FORWARD. It is the 
beginning of the buffer if the direction of the search is REVERSE. The search 
can be a seek search (the default) or an incremental search. In either case, 
ANCHOR disables the continuous mode of searching and applies the pattern 
only once. 


Consider using the built-in procedure ANCHOR to create the pattern for 
which you search. Because an anchored search executes the pattern only 
once, it is faster than either a seek search or an incremental search. 


For more information on patterns or modes of pattern searching, 
see Section 2. 


EXAMPLES 


D patl :> ANCHOR b 'a' b '123' 

This assignment statement creates a pattern that is made up of the character 
a and the digits 1, 2, and 3. When patl is used as a parameter for SEARCH, 
the search does not move from character to character looking for this pattern. 
The search fails if the pattern is not found starting at the current character 
position. 

Q SAMPLE PROCEDURE 


The following procedure starts at the beginning of a buffer and searches 
forward, removing all comments that begin in column 1. The built-in 
procedure ANCHOR in this example ties the search to the first character 
of a line (the current character). This prevents the search function from 
finding and removing exclamation marks in the middle of a line (for example, 
in the FAO directive, !AS). 
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PROCEDURE u8er_reBove_comment8 
! Trap error Be88ages 
0N_ERR0R 

! Stop when end-ol-bulfer ie reached 
IF ERROR « TPU$_ENDOFBUF 
THEN 

MESSAGE (STR (number.removed) * ' Coiments removed'); 
RETURN; 

ENDIF 

END0N_ERR0R 

!Start at beginning of the buffer 
POSITION (BEGINNING.OF (CURRENT_BUFFER)); 
number.removed :> 0; 

LOOP 

!Anchor the pattern In the flrat column 
patl ANCHOR A '!■ A REMAIN; 

!Search for pattern and return a range If found, 
ielae return 0 

rl :> SEARCH (patl, FORWARD); 

IF rlOO 
THEN 

! comment found 80 erase It 
ERASE_LINE; 

number.removed :« number.removed * 1; 

ELSE 

! move to the next line 
MOVE.VERTICAL (1); 

ENDIF; 

ENDLOOP; 

ENDPROCEDURE 
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ANY 

Returns a pattern that matches any single character in the string 
used as a parameter. 

FORMAT 

pattern := ANY (string) 

parameter 

string 

A quoted string, or a variable name representing a string constant that 
contains the characters in the pattern. 

DESCRIPTION 

The built-in procedure ANY can be used with the built-in procedure 
SEARCH. In that case, there is a successful match if any one of the characters 
in the pattern returned is found in the text searched. 

ANY looks for a single matching character for a successful match. The 
built-in procedure SPAN returns a pattern that matches the longest string of 
characters containing only the characters in the pattern. See the description 
of SPAN and SPANL for more information. 

See Section 2 for more information on patterns. 


EXAMPLES 

□ patl ;• ANY ('bljkl') 


This assignment statement creates a pattern that matches any one of the 
characters h, i, j, k, and 1. 

Q SAMPLE PROCEDURE 

The following procedure finds an endprocedure statement that starts in 
column 1 and moves the current character position to the end of the 
statement. 

PROCEDURE us«r_find_eiidprocedure 
LOCAL •ndproeadura.pattarn, ■•arch.range; 

0N_ERR0R 

IF ERROR • TPU$_STRN0TF0UND 
THEN s«arcb_raiiga :■ 0; 

ENDIF; 

ENDON.ERROR; 

endprocedure.pattern 

(LINE_BEGIN k ’•ndprocadure*) k 
(LINE_END I ANY (";!■)): 

8 earcb_raiige ;■ SEARCH (endprocedure.pattern, FORWARD); 

IF aearcb.range ■ 0 

THEN MESSAGE ("Endprocedure statement not found"); 

ELSE POSITION (END.OF (searcb.range)); 

ENDIF; 

ENDPROCEDURE 


4-14 


VAXTPU Built-In Procedures 

APPEND-LINE 


APPEND- 

LINE 


Places the current line at the end of the previous line. 

FORMAT 

APPEND_LINE 

parameters 

None. 

Q£3CRIPTI0N APPEND_LINE to delete line terminators. 

The character position in the line that was the current line before 
APPEND_LINE was executed becomes the current character position. 

RETURN 

STATUS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOCACHE ERROR There is not enough memory to allocate 

a new cache. 

EXAMPLES 


Q APPEND_LINE 

This command adds the current line to the end of the previous line. 

Q SAMPLE PROCEDURE 



The following procedure causes the character preceding the cursor to be 
deleted. If you are at the beginning of a line, the current line is appended to 
the previous line. (This procedure assumes that the window is not shifted—it 
does not work on a shifted window.) 

PROCEDURE user.delete.char 

! If the cursor is at the beginning of the line, 

! append the line to the previous line. 

! Otherwise, delete preceding character. 

IF CURRENT.COLUMN - 1 
THEN APPEND.LINE; 

ELSE ERASE_CHARACTER (-1); 

ENDIF; 

ENDPROCEDURE; 

You can bind this procedure to the DELETE key with the following statement: 

DEFINE_KEY (■user_delete_char’, DEL.KEY) 
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ARB 

Returns a pattern that matches an arbitrary sequence of characters 
starting at the current character position and extending for the length 
you specify. 

FORMAT 

pattern := ARB (integer) 

parameter 

integer 

The number of characters in the pattern. 

DESCRIPTION 

ARB can be used for wildcard matches of fixed length. 

For more information on patterns, see Section 2. 

EXAMPLES 


Q patl ARB (6) 

This assignment statement creates a pattern that matches the next five 
characters starting at the current character position. The characters themselves 
are arbitrary; it is the number of characters that is important for a pattern 
created with ARB. 

Q pat2:° 'J' tc ARB (2) 


g] SAMPLE PROCEDURE 

This assignment statement creates a pattern that matches a string that begins 
with a J and is followed by any two other characters. Names such as Jim, Jan, 
and Joe match pat2. 


The following procedure replaces a prefix of any 3 characters followed by an 
underscore (xxx_) with the string 'user—". It assumes that the buffer is set to 
insert mode. 
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! Replace a prefix of any 3 characters 
! followed by an underscore (xxx_) with the prefix 
! 'user.” throughout a buffer 
PROCEDURE user.replace.prefix 
! Start at top and search forward 
POSITION (BEGINNINC.OF (second_buffer)); 

! Pattern contains an arbitrary sequence of 3 characters and an underscore 
patl:- ARB (3) 

! String that replacees the string found 
replacemsnt.str :> ’user.'; 

LOOP 

found_range :• SEARCH (patl, FORWARD); 

IF found_range <> 0 
THEN 

! Remove the first string and 
! replace it with the new one 
ERASE (found.range); 

POSITION (END.OF (found.range)); 

COPY.TEXT (replacenent.str); 

ELSE 

I exit if you don't find it 
EXITIF; 

ENDIF; 

ENDLOOP; 

ENDPROCEDURE 
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ASCII 

Converts an integer to a string. 

FORMAT 

String := ASCII (integer) 

parameter 

integer 

The decimal value of a character in the DEC Multinational Character Set. 

DESCRIPTION 

This built-in procedure returns a string of length 1, that represents the 
character of the DEC Multinational Character Set that corresponds to the 
integer you specify. This correspondence is determined by the decimal 
representation of die character. Only the low byte of the number is used to 
generate the string. 


EXAMPLES 


my.character :> ASCII(12} 


This assignment statement places the value of the FORM FEED character 
in the variable my—character. If you want to see the representation of the 
character displayed in the message area on the screen, enter the following 
command: 


Q MESSAGE (ASCII (80)) 


MESSAGE (ay.charactar) 


This Statement combines two built-in procedures and causes the ASCII 
character numbered 80 to be printed in the message area. In this case, capital 
P is displayed. 

g] SAMPLE PROCEDURE 

The following procedure includes a tab character in the current buffer. 

! Tab key procedure 

! This procedure puts a tab character In your text 
! 

PROCEDURE uaer.tab 
COPY.TEXT (ASCII (9)): 

ENDPROCEDURE 
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ATTACH 

Deassigns the terminal and enables you to switch control from 
your current process to another process that you have previously 
created. 

FORMAT 

ATTACH 

\ string j ^ 

parameters 

integer 

This integer is the process identification (PID) of the process to which terminal 
control is switched. You must use decimal numbers to specify the PID to 
VAXTPU. 


String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that VAXTPU interprets as a process 
name. 

DESCRIPTION 

To use the built-in procedure ATTACH, you must have previously created 
a subprocess. If the process you specify is not part of the current job or 
does not exist, an error message is displayed. For information on creating 
subprocesses, see the description of SPAWN in this section. 


ATTACH suspends the current VAXTPU process and switches context to 
the process you use as a parameter. If you do not specify a parameter for 
ATTACH, VAXTPU switches control to the parent or owner process. A 
subsequent use of the DCL command ATTACH (or a logout from any process 
except the parent process) resumes the execution of the suspended VAXTPU 
process. 


In all cases, VAXTPU first deassigns the terminal. If a VAXTPU process is 
resumed following a SPAWN or ATTACH command, VAXTPU reassigns the 
terminal and refreshes the screen. 

RETURN 

STATUS 

TPU$_NOPARENT WARNING There is no parent process to which 

you can attach — your current process 
is the top level process. 


EXAMPLES 


D ATTACH 


This command causes VAXTPU to attach to the parent process. 
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Q ATTACH (97899) 

This command causes VAXTPU to attach to the subprocess with the PID 
97899. 

0 ATTACH (■J0NES_2') 

This command changes the terminal's control to the process JONES_2. 
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BEGINNING_OF 


Returns a marker that points to the first position of a buffer or a 
range. 

FORMAT 

marker :=BEGINNING_OF ({ 1) 

1 range ) 

parameters 

buffer 

The buffer whose beginning you want to mark. 


range 

The range whose beginning you want to mark. 

DESCRIPTION 

If you use the marker that is returned by this built-in procedure as a 
parameter for the built-in procedure POSITION, your current character 
position goes to this marker. 


EXAMPLES 

Q beg_maln BEGINNING.OF (main.buffer) 


This assignment statement stores the marker that points to the beginning of 
the main buffer in the variable beg—main. 

Q POSITION (BEGINNING.OF (my.range}) 

This command uses two built-in procedures to move your current character 
position to the beginning of my—range. If my—range is in a visible buffer in 
which the cursor is located, the cursor position is also moved to the beginning 
of my—range. 

After moving to the beginning of a buffer or a range, any characters that you 
insert are entered before the first character position of the buffer or the range. 

g] SAMPLE PROCEDURE 


The following procedure moves to the beginning of the current buffer. If you 
are already at the beginning of the buffer, the message 'Already at top' is 
displayed in the message area. 

PROCEDURE usmr.top 

IF MARK (NONE) • BEGINNING.OF (CURRENT.BUFFER) 

THEN MESSAGE (‘Already at top'); 

ELSE POSITION (BEGINNING.OF (CURRENT.BUFFER)); 

ENDIF; 

ENDPROCEDURE 
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Q SAMPLE PROCEDURE 


The following procedure creates a new buffer, associates the buffer with 
main_window, and maps main_window to the screen. It positions to the top 
of the buffer, prompts the user for the name of a file to include, and reads the 
file into the buffer. 

PROCEDURE ut4r.lnclttda.fil* 

!Cr*at* Scratch Bulfar 

bl :• CREATE_BUFFER ('Scratch Buffer'); 

IMap bl to Main Window 
MAP (maln_wlndow, bl); 

(Read In file name given 

READ.FILE (READ.LINE ('File to Include;'}); 

!Go to top of file 

POSITION (BECINNING.OF (bl)); 

ENDPROCEDURE 
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CALL_USER 


Calls a program written in another language from within VAXTPU. 

The CALI_USER parameters are passed to the external routine 

exactly as you enter them; VAXTPU does not process the 
parameters in any way. The integer is passed by reference, and 
string 1 is passed by descriptor. String2 is the value returned by the 
external program. 


FORMAT string2 := CALI_USER (integer, string 1) 


parameters integer 

The integer that is passed to the user-written program by reference. 

String 1 

The string that is passed to the user-written program by descriptor. 


DESCRIPTION In addition to returning a value (string2) to CALL—USER, the external 

program returns a status code that tells whether the program executed 
successfully. You can trap this status code in an ON—ERROR statement. 

An even-numbered status code (low bit in RO clear) causes the ON—ERROR 
statement to be executed. 

To use the built-in procedure CALL—USER, follow these steps: 

• Write a program in whatever language you choose. The program must be 
a global routine called TPU$CALLUSER. 

• Compile the program. 

• Link the program with an options file to create a shareable image. 

• Define the logical name TPUSCALLUSER to point to the file containing 
your routine. 

• Invoke VAXTPU. 

• From within a VAXTPU session, call your external program to perform 
its function by specifying the built-in procedure CALL—USER with the 
appropriate parameters. If you link your program properly, and if you 
define the logical name TPUSCALLUSER to point to your program, the 
built-in proc^ure CALL—USER passes the parameters you give it to the 
proper routine. 

The CALL—USER parameters are input parameters for the external program 
you are calling. The parameters are "dummy" parameters or placeholders. 
VAXTPU does not process the parameters in any way but passes them 
to the external procedure exactly as you enter them. You must supply 
both parameters even if the routine you are calling does not require that 
information be passed to it. Enter the following null parameters to indicate 
that you are not passing any actual values: 

CALL.USEH (O.**) 
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V-/ 


RETURN 

STATUS 


TPU$_BADUSERDESC ERROR 
TPU$_NOCALLUSER ERROR 


User-written routine incorrectly filled in 
the return descriptor 

Could not find a routine to invoke 


EXAMPLES 

□ ret.valua :• CALL.USER (6, 'ABC') 

This Statement calls a program that the user wrote. Before invoking VAXTPU, 
the user created a logical name, TPU$CALLUSER, that points to the file 
containing the program he wants called by CALL—USER. VAXTPU passes 
the first parameter (6) by reference, and the second parameter ('ABC') by 
descriptor. If, for example, the user program uses an integer and a string as 
input values, the program would process the integer '6' and the string 'ABC'. 
If the program is designed to return a result, the result is returned in the 
variable ret—value. 


Q SAMPLE PROCEDURE 


The following example shows the steps required to use the built-in procedure 
CALL—USER. The routine that is called to do floating point arithmetic is 
written in BASIC. 

1 Write a program in BASIC that does floating point arithmetic on the values 
passed to it. 

!Filename:FLOATARITH.BAS 

1 sub TPUtCALLUSER ( some.integerX , lnput_8tring$ , return_strlng$ ) 

10 f don't check some.integerX because this function only does 
! floating point arithmetic 
20 ! parse the input string 

■ find and extract the operation 
comma.locatlon • pos ( lnput_string$, IX ) 

if comma.locatlon ■ 0 then go to all.done end if 

operation# > segt( Input.strlng#, IX, comma.locatlon - IX ) 

! find and extract the Ist operand 

operandl.location ■ pos ( Input.string#, comma_loeatlon +1 ) 

if operandl.locatlon • 0 then go to all.done end if 

operandl# ° segt( input.strlng#, comma.locatlon IX . A 
operandl.locatlon -1 ) 

I find and extract the 2nd operand 

oparand2_location • pos ( input.string#, operandl.locatlon ‘•'1 ) 

if operand2_locatlon • 0 than 

operand2_locatlon • lent Input.stringt) *' 1 

end if 








Vs-/ 
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operands# ■ segt( Input.strlng#, oparandl.locatlon + IX , k 
operandS.locatlon -1 } 

select operation# ! do the operation 
case 

result# • suit#( operandl# , operands# ) I 

case 

result# ■ dll#( operandl#, operands# ) I 

case 

result# • nuDl#( Val( operandl# ) * Val( operands# ) ) 

case "/" 

result# « numl#( Val( operandl# } / Val( operands# ) ) 
case else 

result# ° "unknown operation.” 
end select 

retum.strlng# ■ result# 

999 all.done: end sub 

2 Compile the program with the following statement. 

# BASIC/LIST FLOATARITH 

3 Create an options file that is used by the linker when you link the BASIC 
program. 

!♦ 

! File: FLOATARITH.OPT 
! 

! Options file to link floatarith BASIC program with VAXTPU 
! 

FLOATARITH.OBJ 
UNIVERSAL>TPU#CALLUSER 

4 Link the program (using the options file) to aeate a shareable image. 

# LINK FLOATARITH/SHARE/OPT/MAP/FULL 

5 Define the logical name TPU$CALLUSER to point to the executable image 
of the BASIC program. 

# DEFINE TPU#CALLUSER device:[directory]FLOATARITH.EXE 

6 Invoke VAXTPU. 

7 Write and compile the following VAXTPU procedure. 

PROCEDURE my.call.user 

ttest the built-in procedure call.user 

LOCAL output, input; 

input :■ READ.LINE ('Call user >'); !Provide a parameter for routine 

output ;• CALL.USER ( 0, input); IValus this routine returns 
message (output); 

ENDPROCEDURE 

8 When you call the procedure my—call—user, you are prompted for 
parameters to pass to the BASIC routine. The order of the parameters 
is operator, number, number. For example, if you enter "+, 3.33, 4.44" 
after the prompt, the result 7.77 is displayed in the message area. 
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CHANGE_CASE 


Modifies the case of all the alphabetic characters in the specified unit 
of text according to the keyword that you supply. 


FORMAT 


f buffer 

CHANGE_CASE (i range 

[ string . 


keyword) 


parameters buffer 

The buffer in which you want to change the case of all the characters. 

range 

The range in which you want to change the case of all the characters. 

String 

The string in which you want to change the case of all the characters. 

keyword 

This keyword specifies the case you want the specified characters to be. The 
valid keywords are LOWER, UPPER, and INVERT: 

• LOWER—The specified characters are changed to lowercase. 

• UPPER—The specified characters are changed to uppercase. 

• INVERT—The specified characters are changed from their current case 
to the opposite case. If the characters are uppercase, they are changed to 
lowercase; if the characters are lowercase, they are changed to uppercase. 


DESCRIPTION CHANGE-CASE does not return a result. It changes the case of the 

characters you specify in place. 





EXAMPLES 

□ CHANGE_CASE (CORRENT.BUFFER, UPPER) 

This command makes all the cheuracters in the current buffer uppercase. If 
you enter this command on the command line of your interface, you see the 
command take effect immediately. If you use this command as a statement 
within a procedure, you see the effect of the statement at the next screen 
update. 

Q CHANGE_CASE (m 7 _range, LOWER) 

This command makes all the characters in my—range lowercase. If my—range 
is part of a buffer that is mapped to a window, you see the command take 
effect immediately. 
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g] SAMPLE PROCEDURE 


The following procedure changes the current line to lowercase. 

PROCEDURE usar_low*rcaae_lin* 

LOCAL thls.line; 
thla_lin« :• ERASE_LINE; 

CHANGE_CASE (tbli.lina, LOWER); 

SPLIT.LINE: 

MOVE_mTICAL (-1): 

COPY.TEXT (tliia.lin*); 

ENDPROCEDURE 


Q SAMPLE PROCEDURE 


The following procedure puts the current text object in uppercase. 

PROCEDURE user.upcasa.ltem 
0N_ERR0R 

I In case no string Is found during search 
MESSAGE ("No current item.'); 

RETURN; 

END0N_ERR0R; 

delimiters + ASCII(9); 

current.item ;■ ANCHOR A SCAN (delimiters); 
item_ranga SEARCH (current.ltem, FORWARD, NO.EXACT); 

CHANGE_CASE (itam_range, UPPER); 

ENDPROCEDURE 



4-27 



VAXTPU Built-In Procedures 

COMPILE 


COMPILE 

Converts VAXTPU procedures and statements into an internal, 
compiled format. Valid items for compilation can be represented by 
a string, a range, or a buffer. COMPILE optionally returns a program. 

FORMAT 

f String 

[program := J COMPILE ( | range ) 

i buffer . 

parameters 

string 

A string that is a valid VAXTPU procedure or statement. 


range 

A range that contains only valid VAXTPU procedures and/or statements. 


buffer 

A buffer that contains only valid VAXTPU procedures and/or statements. 


DESCRIPTION The program that COMPILE optionally returns is the compiled form of 

valid VAXTPU procedures and/or statements. You can assign the compiled 
version of VAXTPU code to a variable name. VAXTPU statements, as well 
as procedure definitions, can be stored in the program variable returned by 
COMPILE. Later in your editing session, you can execute the VAXTPU code 
that you compiled by using the program variable as a parameter for the 
built-in procedure EXECUTE. You can also use the program variable as a 
parameter for the built-in procedure DEFINE _KEY to define a key to execute 
the program. Then you can execute the program by pressing that key. 

COMPILE returns a program variable only if the compilation generates 
executable statements. COMPILE does not return a program variable if you 
compile any of the following items: 

• Null strings or buffers 

• Procedure definitions that do not have any executable statements 
following them 

• Programs with syntax errors 

If you use a string as the parameter for the built-in procedure COMPILE, 
undefined variables or procedure definitions cannot be part of the string. 
Undefined variables and procedure definitions can, however, be part of 
a buffer or range that is used as a parameter for the built-in procedure 
COMPILE. 

If necessary, use the built-in procedure SET (INFORMATIONAL, ON) before 
compiling a procedure interactively to see the compiler messages. Some 
editing interfaces (for example, the EDT Ke)T3ad Emulator) do not display 
informational messages by default. 
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To check the results of a compilation to determine whether execution is 
possible, use the following statement in a program: 

X := COMPILE (ny.range); 
ill the program la non-zero, continue 
IF X <> 0 
THEN . 


ENDIF; 

If X = 0, no program was generated because of compilation errors or because 
there were no executable statements. The statement, "IF x <> 0 THEN" 
allows your program to continue as long as a program was generated. 

You can also use an ON—ERROR statement to check the result of a 
compilation. This statement tells you whether the compilation completed 
successfully; it does not tell you whether execution is possible. You can use 
an ON_E^OR statement when you are compiling only procedure definitions 
with no executable statements following the procedures. 


RETURN 

STATUS 


For a buffer: 

TPU$_EXPECTED WARNING Syntax errors 

TPU$_COMPILEFAIL ERROR Compilation aborted due to syntax 

errors 


EXAMPLES 

□ dwn ;= COMPILE ('M0VE_VERTICAL (1)'} 

This command causes the MOVE—VERTICAL (1) function to be associated 
with the variable dwn. You can use the variable dwn with the built-in 
procedure EXECUTE to cause the current character position to move down 
one line. 

Q user.program :• COMPILE (main_bufler) 

This command compiles the contents of the main buffer. If the buffer 
contains executable statements, VAXTPU returns a program that stores these 
executable commands. If the buffer contains procedure definitions, VAXTPU 
compiles the procedures and lists them in the procedure definition table so 
that you can call them in one of the following ways: 

• Enter the name of the procedure after the appropriate prompt from the 
interface you are using. 

• Call the procedure from within other procedures. 
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COPY_TEXT 


Makes a copy of the text you specify and places it in the current 
buffer. 


FORMAT 


COPY_TEXT ( 


string 

range 

buffer 


) 


parameters string 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that represents the text that you want to 
copy. 

range 

The range that contains the text you want to copy. 

buffer 

The buffer that contains the text you want to copy. 


DESCRIPTION If the current buffer is in insert mode, the text you specify is inserted before 

the current position in the current buffer. If the current buffer is in overstrike 
mode, the text you specify replaces text starting at the current position and 
continuing for the length of the string, range, or buffer. 

Note: You cannot add a buffer or a range to itself. If you try to add a buffer 
to itself, VAXTPU issues an error message. However, VAXTPU does 
not check for this condition for a range. If you are positioned within 
the range represented by the variable my—range, a statement like the 
following may cause an infinite loop: 

COPY.TEXT (my_range) 

Press CTRL/C to stop the loop. 
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RETURN 

STATUS 

For a string: 

TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 


For a range: 

TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 


TPU$_NOCACHE 

ERROR 

There is not enough memory to allocate 
a new cache. 


For a buffer: 




TPU$_NOCOPYBUF 

WARNING 

Trying to copy a buffer to itself is not 
allowed. 


TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 


TPU$_NOCACHE 

ERROR 

There is not enough memory to allocate 
a new cache. 


EXAMPLES 

D COPY.TEXT ('Perseus Is near Andromeda.') 

When the buffer is set to insert mode, this command causes the string 
'Perseus is near Andromeda.' to be placed in front of the current position in 
the current buffer. 

2 COPY.TEXT (ASCII (10)) 

When the buffer is set to overstrike mode, this command causes the ASCII 
character for line feed to replace the current character in the current buffer. 

2 SAMPLE PROCEDUKE 


Using the EOT Keypad Emulator interface, enter the command SHOW 
(KEYWORDS) after the 'TPU Command:" prompt. Position to the beginning 
of the SHOW-BUFFER, and execute the following procedure to get a list of 
the internal integer representation of the VAXTPU keywords. 

PROCEDURE a8er_keyword_iiumbarB 

!N0TE - Before executing this procedure, enter the command 
ISHOW (KEYWORDS), and poeition to the SHOW_BUFFER. 

XX :■ 0; 

LOOP 

EXECUTE ('XX + current.line); 

COPY.TEXT (STR (XX) + ' '): !Insert a TAB between the quotes. 

MOVE.VERTICAL (1); 

IF MARK (NONE) • END.OF (SHOW.BUFFER) 

THEN RETURN 
ENDIF; 

M0VE.H0RIZ0NTAL (- CURRENT.OFFSET); 

ENDLOOP; 

ENDPROCEDURE 
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CREATE^BUFFER 


Defines a new work space for editing text. You can create an 
empty buffer or you can associate an input file name with the buffer. 
CREATE—BUFFER optionally returns a buffer. 


FORMAT llbuffer :=]| CREATE_BUFFER (string 1 i,string2]l) 


parameters string 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that represents the name of the buffer 
you want to create. 

string2 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that represents the file specification 
of an input file that is read into the buffer. 


DESCRIPTION Although you do not always have to assign the buffer that you create to a 

variable, you need to make a variable assignment if you want to refer to 
the buffer for future use. The buffer variable on the left-hand side of an 
assignment statement is the item that you must use when you specify a buffer 
as a parameter for other VAXTPU built-in procedures. For example, to move 
to a buffer for editing, enter the buffer variable after the built-in procedure 
POSITION: 

my_buller_variablo :• CREATE_BUFFEB ('my.buffer.name', 'my.file.name'); 

POSITION (my.buffer.varlable) 

The buffer name that you specify as the first parameter for the built-in 
procedure CREATE—BUFFER, for example, 'my—buffer—name', is used by 
VAXTPU to identify the buffer on the status line. You can change the status 
line with the built-in procedure SET (STATUS—LINE, . . . ). 

You can create multiple buffers. Buffers can be empty or they can contain 
text. The current bu&r is the buffer in which any VAXTPU commands that 
you execute take effect (unless you specify another buffer.) Only one buffer 
can be the current buffer. See the built-in procedure CURRENT—BUFFER for 
more information. 

A buffer is visible when associated with a window that is mapped to the 
screen. A buffer can be associated with multiple windows, in which case any 
edits that you make to the buffer are reflected in all of the windows in which 
the buffer is visible. To get a list of all the buffers in your editing context, use 
the built-in procedure SHOW (BUFFERS). 

The following keywords used with the built-in procedure SET allow you 
to establish attributes for buffers. The text describes the default for the 
attributes: 

• SET (EOB—TEXT, buffer, string)—The default end-of-buffer text is [EOB]. 

• SET (FORWARD, buffer)—The default direction is FORWARD. 
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• SET (INSERT, buffer)—The default mode of text entry is INSERT. 

• SET (MARGINS, buffer, integerl, integer2)—The default left margin is 1 
and the default right margin is 80. 

• SET (MAX—LINES, buffer, integer)—The default maximum number of 
lines is 0 (in other words, this feature is turned off). 

• SET (NO—WRITE, buffer, [keyword])—By default, when you exit from 
VAXTPU, the buffer is written, if modified. 

• SET (OUTPUT-FILE, buffer, string)—The default output file is the input 
file name and the highest existing version number for that file plus 1. 

• SET (OVERSTRIKE, buffer)—The default mode of text entry is INSERT. 

• SET (PERMANENT, buffer)—By default, the buffer can be deleted. 

• SET (REVERSE, buffer)—The default direction is FORWARD. 

• SET (SYSTEM, buffer)—By default, the buffer is a user buffer. 

• SET (TAB—STOPS, buffer, | | )—The default tab stops are set 

every 8 character positions. 

See the built-in procedure SET for more information on these items. 


RETURN 

STATUS 


TPU$_DUPBUFNAME WARNING First argument must be a unique string. 


EXAMPLES 

□ nb := CREATE_BUFFER ('new.buMer', 'login.com') 

This command creates a buffer called new—buffer and stores a pointer to the 
buffer in the variable nb. Use the variable nb when you want to specify this 
buffer as a parameter for VAXTPU built-in procedures. The file specification, 
Togin.com', is the input file for new—buffer. 

Q SAMPLE PROCEDURE 


The following procedure creates the help buffer. 

PROCEDURE u*«r_holp_bulfor 

holp.bul CREATE.BUFFERCholp.bul"); 

SET (EOB.TEXT, holp.buJ, "[End of HELP)"); 
SET (NO.WRITE, holp.bul); 

SET (SYSTEM, holp.buf); 

ENDPROCEDURE 
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-MAP 

y 

CREATE. 

_KEY_MAP 



Creates and names a key map. CREATE_KEY_MAP optionally 
returns a string that is the name of the key map created. 


FORMAT 

Estring2 :=1 CREATE_KEY_MAP (string!) 


parameters 

string 1 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key map you create. 

y 

QE3CRIPTION ^ ^ dehnltions. Key maps allow you to easily and 

quickly manipulate key definitions as a group. Key maps and their key 
definitions are saved in section files. The default key map for VAXTPU is 
TPU$KEY_MAP contained in the default key-map list TPU$KEY_MAP_LIST. 
(The EVE interface, however, does not use default key map, TPU$KEY_MAP.) 

See the description of the built-in procedure CREATE _KEY_MAP_LIST for 
information on key-map lists. 



When you create a key map, its keys are undefined. Each key map can hold 
definitions for all characters in the DEC Multinational Character Set, and all 
the keypad keys and the function keys, in both their shifted and unshifted 
forms. Each key map has its own name (a string). This name cannot be the 
same name as that of either another key map or a key-map list. 

y 

RETURN 

STATUS 

TPU$_DUPKEYMAP WARNING The name for the key map in the string 

argument is already defined as a key 
map. 

w 


EXAMPLE 


SAMPLE PROCEDURE 


The following procedure creates a key map and defines two keys in the key 
map. The name of the key map is stored in the variable sampk-key-Jtiap. 

PROCEDURE inlt_taapl«.k«7.iBap 

saBpla_ke7_map :• CREATE.KEY.HAP Caampla.kay.map"); 

DEFINE_KEY ("EXIT", CTRL.Z.KET, "Exit application". Baapla_kay_Bap); 
DEFINE.KEY ("COPY.TEXT ('XYZZY’)", CTRL_B_KEY, "Magic Word", •anpla.kay.map); 

ENDPROCEDURE; 
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CREATE_KEY^MAP_LIST 


Creates and names a key-map list, and also specifies the initial key 
maps in the key-map list it creates. CREATE_KEY_MAP_LIST 
optionally returns a string that is the name of the key-map list 
created. 


FORMAT [Strings :=]] 

CREATE_KEY_MAP_LIST (stringh string2i,...]) 


parameters string 1 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key-map list that you create. 

strimgZ 

Strings that specify the names of the initial key maps within the key-map list 
you create. 


DESCRIPTION A key -maj) list is a set of key maps. Key-map lists allow you to quickly change 

the procedures bound to your keys. VAXTPU provides the default key map 
list, TPU$KEY_MAP_LIST containing the default key map, TPU$KEY_MAP. 
(See the description of the built-in procedure CREATE _ICEY_MAP for more 
information on key maps.) 

The built-in procedure CREATE _KEY_MAP_LIST creates a new key-map list, 
names the key-map list and specifies the initial key maps contained in the 
list. 

When you create a new key-map list, unbound printable characters are 
inserted into the current buffer by default. This can be modified with 
the built-in procedure SET (SELF-INSERT, ... ). A newly created key- 
map list is not bound to any buffer. Use the built-in procedure SET 
(KEY-MAP—LIST, .. . ) to bind a key-map list to a buffer. When you position 
to the buffer, the key-map list that is bound to the buffer is automatically 
activated. A newly created key-map list has no procedure defined to be 
called when an undefined key is referenced. You can define such a procedure 
with the built-in procedure SET (UNDEFINED—KEY, ... ). The default is to 
display the message 'key has no definition". 

Key-map lists are saved in section files, along with any undefined key 
procedures and the SELF—INSERT settings. 


RETURN 

STATUS 


TPU$_DUPKEYMAP WARNING 

TPU$_DUPKEYMAPLIST WARNING 
TPU$_NOKEYMAP WARNING 


The string argument is already defined 
as a key map. 

The string argument is already defined 
as a key-map list. 

The string 1 argument is not a defined 
key map. 
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EXAMPLE 

SAMPLE PROCEDURE 


The following procedure creates two key maps, and groups them into a 
key-map list. 

PROCEDURE lnit_belp_k«y_nap_llst 

help.user.keys :• CREATE_KEY_MAP ("halp.UBer.keys”); 

help.key 8 CREATE_KEY_MAP ("help.keys"); 

help.key.llst :• CREATE_KEY_MAP_LIST ("halp_key_li»t*, halp_UBer_key«, halp.kays); 
ENDPROCEDURE; 


* 
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CREATE__PROCESS 


Starts a subprocess and associates a buffer with it. You can 
optionally specify an initial connmand to send to the subprocess. 
CREATE—PROCESS returns a process. 


FORMAT process :=CREATE_PROCESS (buffer[,string]) 


parameters buffer 

The buffer in which VAXTPU stores output from the subprocess. 

String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that represents the first command 
that you want to send to the subprocess. If you do not want to include the 
first command in the built-in procedure CREATE—PROCESS, see the built-in 
procedure SEND for a description of how to send the first or subsequent 
commands to a subprocess. 


DESCRIPTION You can create multiple subprocesses. When you exit from VAXTPU, any 

subprocesses you have created with CREATE—PROCESS are deleted. If 
you want to remove a subprocess before exiting, use the built-in procedure 
DELETE with the process as a parameter (DELETE (pi)), or set the process to 
integer zero (procl := 0). 

CREATE—PROCESS creates a subprocess within a VAXTPU session and all 
of the output from the subprocesses goes into a VAXTPU buffer. You cannot 
run a program or utility that takes over control of the screen from a process 
created with this built-in procedure. (See Section 2.10 for a list of subprocess 
restrictions.) You can however use the built-in procedure SPAWN to create 
a subprocess that suspends your VAXTPU process and places you directly at 
DCL level. You can then run programs such as FMS or PHONE that control 
the whole screen. 

You return to VAXTPU from a subprocess by using the built-in procedure 
ATTACH with a subprocess as a parameter, or by logging out of the 
subprocess that you spawned. 


RETURN 

STATUS 


TPU$_DUPBUFNAME 

TPU$_CREATEFAIL 


WARNING First argument must be a unique string 
WARNING Unable to activate the subprocess 


4-37 



VAXTPU Built-In Procedures 

CREATE_PROCESS 


EXAMPLES 

Q my.nall.process CREATE.PROCESS (second_bufler, "mall”) 

The preceding assignment statement creates a subprocess and specifies 
second-buffer as the buffer in which the output from the subprocess is 
stored, It also sends the DCL MAIL command as the first command to be 
executed. 

Q SAMPLE PROCEDURE 


The following procedure creates a buffer to hold the output from the DCL 
commands executed by the subprocess. 


!Create a buffer to hold the output from the DCL commands 
!"SET NOON" and "DIRECTORY". 

! 

PROCEDURE user_dcl_process 

dcl.buffer CREATE.BUFFER Cdcl.buffer'): 

MAP (maln_window, dcl.buffer): 

By.dcl.procesa ;« CREATE.PROCESS (dcl.buffer. 'SET NOON'); 
message ('Creating DCL subprocess...'); 

SEND ('DIRECTORY', my.dcl.process); 

ENDPROCEDURE 
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CREATE_RANGE 


Returns a range that includes two markers and all the characters 
between them. You must specify how the characters in the range 
are to be displayed when they are visible on the screen (no special 
video, reverse video, bolded, blinking, or underlined). 


FORMAT range := 

CREATE—RANGE (markerl, marker2, keyword) 


parameters markerl 

The character position at which the range begins. 

marker2 

The character position at which the range ends. 

keyword 

You must use one of the following keywords: 

• NONE—Applies no video attributes to the characters in the range. 

• BOLD—Causes the characters in the range to be bolded. 

• BLINK—Causes the characters in the range to blink. 

• REVERSE—Causes the characters in the range to be displayed in reverse 
video. 

• UNDERLINE—Causes the characters in the range to be underlined. 


DESCRIPTION The built-in procedure MARK creates the markers that delimit a range. 

CREATE—RANGE establishes a range structure that is delimited by the 
markers you specify. You can create multiple ranges in a buffer. V^en you 
apply video attributes to a range, you can see the range if it is in a visible 
buffer. 

If you clear the contents of a range with the built-in procedure ERASE, the 
range structure still exists. The range structure and any video attribute that 
you specified for the range move to the next closest character. The next 
closest character is always a character following the range. To remove the 
range structure use the built-in procedure DELETE or set the variable to 
which the range is assigned to zero (rl := 0). 

If the end of the range is at the end of a line (beyond the last printable 
character), marker2 is a nonprinting character. VAXTPU does not apply video 
attributes to nonprinting characters. However, if you insert new characters 
before the end of the range, these characters have the video attribute that was 
specified when the range was created. 
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RETURN 

STATUS 


TPU$_NOTSAMEBUF WARNING First and second marker are in different 

buffers. 


EXAMPLES 

D my.range :■ CREATE_RANGE (fir8t_fflarker, sacond.marker, BOLD) 

The assignment statement creates a range starting at first-marker and ending 
at second-marker. When this range is visible on the screen, the characters in 
the range are bolded. 

Q SAMPLE PROCEDURE 


The following procedure erases the text in the current buffer, starting at the 
current character position to the end of the buffer. 


PROCEDURE user.eraae.to.EOB 


LOCAL atart.ol.range, here.to.EOB; 

atart.ol.range :■ MARK (NONE); 

here.to.EOB :■= CREATE.RANGE (8tart.ol.range, 

END.OF(CURRENT.BUFFER). 
NONE); 

ERASE (here_to_E0B) 


ENDPROCEDURE; 
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CREATE_WINDOW 


Defines a screen area called a window. You must specify the screen 
line number at which the window starts, the length of the window, 
and if the status line is displayed. CREATE_WINDOW optionally 
returns a window. 


FORMAT {[window :=]{ 

C RBATE_WI N DOW (integer 1, integer2, keyword) 


parameters integerl 

The screen line number at which the window starts. 

integer2 

The number of rows in the window. 

keyword 

The keyword describing the state of the status line. The status line occupies 
the last row of a window. The valid keywords are ON or OFF: 

• ON—Indicates that a status line should be displayed. By default, the 
status line is displayed in reverse video and contains the following 
information about the buffer that is currently mapped to the window: 

— The name of the buffer that is associated with the window. 

— The name of the file that is associated with the buffer, if one exists. 

See SET (STATUS-LINE) for information on changing the video attributes 
of the status line and/or the information displayed on the status line. 

• OFF—Suppresses the display of the status line. 


DESCRIPTION CREATE—WINDOW optionally returns a window. If you want to use the 

window that you create as a parameter for any other built-in procedure, then 
you should specify a variable into which the window is returned. 

You can create multiple windows on the screen, but only one wrindow can 
be the current window. The cursor is positioned in the current window. The 
current wdndow and the current buffer are not necessarily the same. 

To make a window visible, you must associate a buffer with a window and 
map the window to the screen. The following command maps main—window 
to ^e screen: 

MAP (iuiln_window, maln_buffer) 

See the built-in procedure MAP for further information. 

The following keywords used with the built-in procedure SET allow you to 
establish attributes for windows. This list shows the default for the attributes: 


• SET (PAD, window, ke)rword)—By default, there is no blank padding on 
the right. 
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• SET (SCROLLING, window, keyword, integer 1, integer2, integers)—The 
default cursor limit for scrolling at the top of the screen is the first line 
of the window; the default cursor limit for scrolling at the bottom of the 
screen is the bottom line of the window. If the terminal type you are 
using does not allow you to set scrolling regions, the window is repainted. 

• SET (STATUS-LINE, window, keyword, string)—The status line may be 
ON or OFF according to the keyword specified for the built-in procedure 
CREATE—WINDOW. See the preceding description of the keyword ON 
for information about the default attributes of a status line. 

• SET (TEXT, window, keyword)—By default, the text is set to 
BLANK—TABS (tabs are displayed as blank spaces). 

• SET (VIDEO, window, keyword)—There are no video attributes by 
default. 

• SET (WIDTH, window, integer)—By default, the width is the same as the 
physical width of the terminal screen when the window is created. 

See the built-in procedure SET for more information on these items. 


RETURN 

STATUS 


TPU$_BADWINDLEN WARNING Invalid window length 

TPU$_BADFIRSTLINE WARNING Invalid first line for window 


EXAMPLES 

□ new.wlndow CREATE.WINOOW (11, 10, ON) 

This assignment statement creates a window that starts at screen line number 
11 and is 10 rows long, and assigns it to the variable new—window. A status 
line is displayed as the last row of the window. To make this window visible, 
you must associate an existing buffer with it and map the window to the 
screen with the following command: 

MAP (new.wlndow, buffer.variable) 


Q SAMPLE PROCEDURE 


The following procedure creates a window called new—window that starts at 
screen line 1 and that is 21 lines long. No status line is displayed. Tabs are 
displayed as special graphic characters. The buffer new—buffer, which is set 
to NO—WRITE, is associated with the window. The window is mapped to the 
screen. 

PROCEDURE uaar.maka.window 

naw.window CREATE.WIND0W(1, 21. OFF); 

SET (TEXT, naw.window, GRAPHIC.TABS); 

naw.buffer ;« CREATE.BUFFER ('user.buffer.name'); 

SET (NO.WRITE, naw.buffer); 

MAP (new.wlndow, naw.buffer); 

ENDPROCEDURE 
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CURRENT- 

-BUFFER 


Returns the buffer in which you are currently positioned. 

FORMAT 

buffer := CURRENT_BUFFER 

parameters 

None. 

DESCRIPTION 

The current buffer is the work space in which any VAXTPU commands you 
execute take effect (unless you specify that a command should take effect in 
another buffer). The current character position is in the current buffer. Note 
that the current character position is not necessarily the same as the current 
cursor location. 

RETURN 

STATUS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

EXAMPLES 


D my_cur_bttl CURRENT.BUTFER 

This assignment statement stores a pointer to the current buffer in the variable 
my—curJiuf. 

Q SHOW (curke:nt_buffer) 

This command returns the buffer in which you are currently positioned and 
uses that buffer as the parameter for the built-in procedure SHOW. 

g] SAMPLE PROCEDUHE 


This procedure changes the direction of the current buffer from its current 
setting. 

PROCEDURE user.toggla.dlrectlon 
IF CURRENT_DIRECTION « FORWARD 

THEN SET (REVERSE. CURRENT_BUFFER); 

ELSE SET (FORWARD. CURRENT.BUFFER); 

ENDIF; 

ENDPROCEDURE 


4-43 


VAXTPU Built-In Procedures 

CURRENT-CHARACTER 


CURRENT. 

.CHARACTER 


Returns a string one character long for the character at the current 
character position in the current buffer. 

FORMAT 

String := CURRENT_CHARACTER 

parameters 

None. 

DESCRIPTION 

The current character position is the position at which any VAXTPU 
commands that you execute take effect by default. You can explicitly specify 
that a command take effect at another position. 

If the current character position is at the end of a line, 
CURRENT-CHARACTER returns a null string. If the current character 
position is at the end of a buffer, CURRENT-CHARACTER returns a null 
string and also signals a warning. 

RETURN 

STATUS 

TPU$—NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOEOBSTR WARNING You are positioned at the EOB (end of 

buffer) mark. 


EXAMPLES 


D my.cur.char CURREKT.CHARACTER 

This assignment statement stores the string that represents the current 
character in the variable my—cur—.char. 

Q MESSAGE (CURRENT.CHARACTER) 

This statement returns the string that represents the current character and 
uses this string as the parameter for the built-in procedure MESSAGE. 

s SAMPLE PROCEDURE 


The following procedure writes the character that is at the current character 
position into the message area. 

PROCEDURE us«r_dl8play_carrent.character 

! This procedure returns the ASCII character 
! in the current character position 
ascii.char ;» CURRENT.CHARACTER; 

IF ascii.char <> "" 

THEN MESSAGE ("The current character is ” ascii.char); 

ELSE MESSAGE ("There is no current character." ); 

ENDIF; 

ENDPROCEDURE; 
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CURREIMT-COLUMN 


Returns an integer that is the current column number of the cursor 
on the screen. 


FORMAT integer CURRENT.COLUMN 


parameters None. 


DESCRIPTION The current column is the column at which the cursor is positioned on the 

screen. The column numbers range from one on the extreme left of the screen 
to the maximum value allowed for the terminal type you are using on the 
extreme right of the screen. 

The value returned by the built-in procedure CURRENT-COLUMN and the 
value returned by GET—INFO (SCREEN, "current—column") are equivalent. 

When you execute CURRENT—COLUMN within a procedure, the integer 
returned may not reflect changes in the cursor location that were caused by 
previously executed statements in the procedure. The reason that the value 
may not be the current value is that VAXTPU generally does not update the 
screen until all statements in a procedure are executed. 

Note: When you execute CURRENT—COLUMN within a procedure, the return 
value may not reflect changes in the current position that occurred 
previously within the procedure. If you want the cursor position 
to reflect the actual editing location, put the statement UPDATE 
(CURRENT—WINDOW) immediately before any statements containing 
CURRENT—COLUMN in your procedure. 

If you do not want to cause an explicit update of a window to get the current 
value for CURRENT—COLUMN, you can use one of the following suggestions 
to get the current column value; 

1 If you are using free cursor movement (CURSOR—VERTICAL, 
CURSOR—HORIZONTAL), the built-in procedures GET—INFO 
(CURRENT-WINDOW, "current—column") and GET—INFO (window- 
variable, "current—column") return the column number that the cursor 
would occupy if you caused an explicit screen update. 

2 If you are using bound cursor movement (MOVE—VERTICAL, 

MOVE—HORIZONTAL), or any other built-in procedures that cause cursor 
movement because of character movement within a buffer, and if the 
window is not shifted, the built-in procedure GET—INFO (buffer—variable, 
"offset—column") returns the column number that the current offset in the 
buffer would have if it were mapped to a window, and if you were to 
explicitly force a screen update. 

If a window is shifted, CURRENT—COLUMN still returns the current column 
number of the cursor on the screen. However, the value returned by x := 
GET—INFO (buffer, "offset—column") includes the number of columns by 
which the window is shifted. For example, if a window is shifted to the 
left by 8 columns, CURRENT—COLUMN returns the value 1, while x := 
GET—INFO (buffer, 'offset—column") returns the value 9. 
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EXAMPLES 

D ay.cur.col CURRENT.COLUMN 

This assignment statement stores the column position of the cursor in the 
variable my^cur-col. 

Q MESSAGE (STR (CURRENT.COLUMN)) 

This statement combines three VAXTPU built-in procedures. 
CURRENT-COLUMN returns the integer that is the current column position, 
STR converts the integer to a string, and MESSAGE writes this string to the 
message buffer. 

s SAMPLE PROCEDURE 


The following procedure splits a line at the current character position. If the 
current character position is column 1, row 1, the procedure causes the screen 
to scroll. 

PROCEDURE user.spllt.llne 
LOCAL old_po8ltlon, new.poaition; 

SPLIT_LINE: 

IF (CURRENT.ROW » 1) AND (CURRENT.COLUMN - 1) 

THEN 

old.po8ltion ;• MARK (NONE); 

SCROLL (CURRENT.WINDOW, -1); 
new.pa8ltlon HARK (NONE); 

IMake 8ure we acrolled before doing CURSOR.VERTICAL 
IF new.poaition <> old.po8ition 
THEN 

CURSOR.VERTICAL (1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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CURRENT- 

.DIRECTION 


Returns a keyworci (FORWARD or REVERSE) that indicates the 
current direction of the current buffer. See also the descriptions 
of the built-in procedures SET (FORWARD, .. . ) and SET 
(REVERSE_). 

FORMAT 

keyword := CURRENT_DIRECTION 

parameters 

None. 

DESCRIPTION 

If the keyword FORWARD is returned, the current direction is toward the end 
of the buffer. If the ke 5 nvord REVERSE is returned, the current direction is 
toward the beginning of the buffer. 

RETURN 

STATUS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

EXAMPLES 


D ny.cur.dir := CURRENT.DIRECTION 

This assignment statement stores in the variable my-xur—dir the keyword that 
indicates whether the current direction setting for the buffer is FORWARD or 
REVERSE. 


Q SAMPLE PROCEDURE 


This procedure writes a message to the message buffer that indicates the 
current direction of character movement in the buffer. 


PROCEDURE user.sbow.dlrectlon 


IF CURRENT_DIRECTION 
THEN my_mea8agel 
ELSE my.me88aga2 
EMDIF; 

ENDPROCEDURE; 


FORWARD 

MESSAGE ("Forward"); 
MESSAGE ("Rsverae"); 
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CURRENT. 

.LINE 


Returns a string that represents the current line. The current line is 
the line that contains the current character position. 

FORMAT 

String :=CURRENT_UNE 

parameters 

None. 

DESCRIPTION 

If you are positioned on a line that has a length of 0, CURRENT-LINE 
returns a string of length 0. If you are positioned at the end of the buffer, 
CURRENT-LINE returns a string of length 0 and also signals a warning. 

RETURN 

STATUS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOEOBSTR WARNING You are positioned at the EOB (end of 

buffer) mark. 

EXAMPLES 


Q my.cur.lin :• CURRENT.LINE 

This assignment statement stores in the variable my—cur—tin the string that 
represents the current line. The current line is the line in the current buffer 
that contains the current character position. 


Q SAMPLE PROCEDURE 

The following procedure returns true if the current line looks like a runoff 
command (starts with a period followed by an alphabetic character, a 
semicolon, or an exclamation point), otherwise it returns false. The procedure 
assumes that the cursor was at start of line, and moves it back to start of line 
when done. 

PROCEDURE us«r_runofl_line 
IF LENGTH (CURRENT.LINE) < 2 
THEN uaar.rttnofl.line :« 0; 

ELSE 

IF CURRENT.CHARACTER <> ".■ 

THEN 

user.runoll.line :• 0; 

ELSE M0VE.H0RIZ0NTAL (1); 

IF INDEX 

(•abcdefghijklmiopqrstuvincyzABCDEFGHIJKLMNOPqRSTUVWXrZ!; ”. 
CURRENT.CHARACTER) ■ 0 

THEN user.nmofl.line :■ 0; 

ELSE user.nuoff.lina ;« 1; 

ENDIF; 

M0VE.H0RIZ0NTAL (-1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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CURRENT- 

-OFFSET 

Returns an integer for the offset of the current character position 
within the current line. 

FORMAT 

integer := CURRENT_OFFSET 

parameters 

None. 

DESCRIPTION 

The current offset is the number of positions a character is located from 
the first character position in the current line (offset 0). In VAXTPU, the 
leftmost character position is offset 0, and this offset is increased by 1 for each 
character position (including the TAB character) to the right. 

If you are using an interface with free cursor motion, when you move beyond 
the end of a line, CURRENT-OFFSET makes the current cursor position the 
new end of line. 

If the current offset equals the length of the current line, you are positioned 
at the end of the line. 

RETURN 

STATUS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

EXAMPLES 



D my.cur.ofl CURRENT.OFFSET 


This assignment statement stores the integer that is the offset position of the 
current character in the variable my—cur—off. 

Q SAMPLE PROCEDURE 


The following procedure uses the built-in procedure CURRENT-OFFSET to 
determine if the editing position is at the beginning of a line. If the position is 
at the beginning, the procedure appends the current line to the previous line, 
otherwise it deletes the previous character. (Compare this procedure with the 
procedure used as an example for the built-in procedure APPEND_LINE.) 

PROCEDURE U8er_d«lete 

IF CURRENT.OFFSET « 0 
THEN APPEND_LIHE; 

ELSE ERASE_CHARACTER (-1); 

ENDIF; 

ENDPROCEDURE 
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CURRENT^ROW 

Returns an integer that is the screen line on which the cursor is 
located. 


FORMAT integer := CURRENT_ROW 

parameters None. 


DESCRIPTION The current row is the screen line on which the cursor is located. The screen 

lines are numbered from 1 at the top of the screen to the maximum number 
of lines available on the terminal. You can get the value of the current row 
by using the built-in procedure GEIUNFO (SCREEN, "current-row"). 

Note: When you execute CURRENT—ROW within a procedure, the return value 
may not reflect changes in the current position that occurred previously 
within the procedure. If you want the cursor position to reflect the actual 
editing location, put the statement UPDATE (CURRENT-WINDOW) 
immediately before any statements containing CURRENT—ROW in your 
procedure. 

EXAMPLES 

Q my_cur_row :• CURRENT.ROW 

This assignment statement stores in the variable my—cur—row the integer that 
is the screen line number on which the cursor is located. 

Q SAMPLE PROCEDURES 

The following procedures cause the cursor to go up or down on the screen. 
Because CURSOR—VERTICAL crosses window boundaries, you must use 
the built-in procedure SCROLL to keep the cursor motion within a single 
window if you are using free cursor motion. (See CURSOR—HORIZONTAL 
and CURSOR—VERTICAL.) You can bind these procedures to a key so that 
the cursor motion can be accomplished with a single keystroke. 

PROCEDURE utar_go_up 

IF CURRENT_ROW • GET.INFO (CURRENT.WINDOW. "vialbla.top*) 

THEN SCROLL (CURRENT.WINDOW, -1); 

ELSE CURSOR.VERTICAL (-1); 

ENDIF; 

ENDPROCEDURE 

PROCEDURE U8«r_go_down 

IF CURRENT_ROW - GET.INFO (CURRENT.WINDOW, "viBible.bottom") 

THEN SCROLL (CURRENT.WINDOW, 1); 

ELSE CURSOR_VERTICAL (1); 

ENDIF; 

ENDPROCEDURE 
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CURRENT- 

.WINDOW 


Returns the window in which the cursor is visible. 

FORMAT 

window := CURRENT_WINDOW 

parameters 

None. 

DESCRIPTION 

The current window is the window that you most recently positioned to with 
the built-in procedure POSITION, or the window that was most recently 
mapped to the screen with the built-in procedure MAP. The cursor position 
is in the current window at the screen coordinates current-column and 
current-row. The current buffer is not necessarily associated with the current 
window. 

RETURN 

STATUS 

TPU$_WINDNOTMAPPED WARNING No windows are mapped to buffers on 

the screen. 

EXAMPLES 


D my.cur.win :» CURRENT.WINDOW 


This assignment statement stores the window that holds the cursor in the 
variable my—cur—win. 

Q SAMPLE PROCEDURE 


The following procedure determines the length of the current window and 
then uses that value as a parameter for the built-in procedure SCROLL. 

PROCEDURE U8er_n«xt_8craen 
LOCAL how_ffluch_8croll; 

how_much_8eroll ;« GET.INPO (CURRENT.WINDOW, "vi8lbl8_length"); 

SCROLL (CURRENT.WINDOW, how_much_8croll); 

ENDPROCEDURE 
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CURSOR_HORIZONTAL 


Moves the cursor position across the screen the number of screen 
columns that you specify. 


FORMAT CURSOR-HORIZONTAL (integer) 


parameters integer 

The signed (+/“) integer value that specifies the number of screen columns to 
move the cursor position. 


DESCRIPTION A positive integer moves the cursor position to the right. A negative integer 

moves the cursor position to the left. The cursor does not move beyond the 
left or right edge of the window in which it is located. Therefore, even if the 
screen is 132 columns wide, the movement of the cursor stops at column 80, 
if the window in which the cursor is located is only 80 columns wide. Editing 
cannot be done outside the bounds of a window. 

This built-in procedure can be used to provide free cursor movement in a 
horizontal direction. Free cursor movement means that the cursor is not tied 
to text, but that it can move across all available columns in a screen line. 

If you use this built-in procedure within a procedure, screen updating occurs 
as follows: 

1 If you execute a built-in procedure that modifies the buffer or the 
current character position within the buffer before you issue the 
call to CURSOR-HORIZONTAL, the screen is updated before 
CURSOR-HORIZONTAL is executed. This action ensures that the 
horizontal movement of the cursor starts at the correct character position. 

2 The screen manager does not update the screen (except in the preceding 
case) to reflect the horizontal movement of the cursor until the procedure 
has finished executing and control is returned to the screen manager. 

CURSOR—HORIZONTAL does not work if you use any input device other 
than a video terminal supported by VAXTPU. See Appendix B for information 
on terminals that VAXTPU supports. 


EXAMPLES 

□ amS0R_H0RIZ0NTAL (1) 


This command moves the cursor position one screen column to the right. 
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Q SAMPLE PROCEDURE 


The following procedures provide for free cursor motion to the right and to 
the left. These procedures can be bound to keys (for example, the arrow keys) 
so that the movement can be accomplished with a single keystroke. 

PROCEDURE uMr.lrM.curtor.rlght 
CURSOR_HORIZOHTAL (1); 

ENDPROCEDURE: 

PROCEDURE user.lrM.curior.left 
CURSOR_HORIZONTAL (-1); 

ENDPROCEDURE; 
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CURSOR-VERTICAL 


Moves the cursor position up or down the screen by the number of 
screen lines that you specify. 


FORMAT CURSOR-VERTICAL (integer) 


parameter integer 

The signed (+/~) integer value that specifies how many screen lines to move 
the cursor position. 


DESCRIPTION A positive integer moves the cursor position down. A negative integer moves 

the cursor position up. 

The cursor does not move beyond the top or the bottom edges of the screen. 
However, CURSOR-VERTICAL can cross window boundaries. If there 
are multiple windows on the screen, CURSOR—VERTICAL can move the 
cursor position to a new window. The new window in which the cursor is 
positioned becomes the current window. 

The column position of the cursor remains unchanged unless vertical 
movement would position the cursor outside the bounds of a window whose 
width is narrower than the width of the previous window. In this instance, 
the cursor moves to the left until it is positioned within the right boundary of 
the narrower window. 

CURSOR—VERTICAL can be used to provide free cursor movement in a 
vertical direction. Free cursor movement means that the cursor is not tied to 
text, but that it can move up and down all lines on the screen which can be 
edited. 

CURSOR—VERTICAL positions the cursor only in screen areas in which 
editing can occur. The cursor is not positioned, for example, on a 
STATUS—LINE of a window, in the PROMPT-AREA, or in an area of the 
screen that is not part of a window. 

If you use CURSOR—VERTICAL within a procedure, screen updating occurs 
as follows: 

1 If you execute a built-in procedure that modifies the buffer or the 
current character position within the buffer before you issue the call 

to CURSOR—VERTICAL, the screen is updated before VAXTPU executes 
CURSOR—VERTICAL so that the vertical movement of the cursor starts at 
the correct character position. 

2 The screen manager does not update the screen (except in the preceding 
case) to reflect the vertical movement of the cursor until the procedure has 
finished executing and control is returned to the screen manager. 

CURSOR—VERTICAL does not work if you use an input device other than 
a video terminal supported by VAXTPU. See Appendix B for information on 
terminals that VAXTPU supports. 
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EXAMPLES 

□ CURSOR.VERTICAL (6) 

This command moves the cursor position five lines toward the bottom of the 
screen. 

Q SAMPLE PROCEDURE 

The following procedures provide for free cursor motion up and down on the 
screen. These procedures can be bound to keys (for example, the arrow keys) 
so that the movement can be accomplished with a single keystroke. 

Unlike CURSOR-HORIZONTAL, CURSOR-VERTICAL crosses window 
boundaries. The built-in procedure SCROLL in the sample procedures keeps 
the cursor motion within a single window. 

! Free cursor motion procedures 
PROCEDURE user_free_cursor_up 
IF GET.INFO (CURRENT.WINDOW, “CURRENT_ROW") - 
GET.INFO (CURRENT.WINDOW, "VISIBLE_TOP") 

THEN SCROLL (CURRENT.WINDOW, -1); 

ELSE CURSOR.VERTICAL (-1); 

ENDIF; 

ENDPROCEDURE; 

PROCEDURE user.free.cursor.down 

IF GET.INFO (CURRENT.WINDOW, "CURRENT.ROW") * 

GET.INFO (CURRENT.WINDOW, "VISIBLE.BOTTOM") 

THEN SCROLL (CURRENT.WINDOW, 1); 

ELSE CURSOR.VERTICAL (1): 

ENDIF; 

ENDPROCEDURE; 
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DEFINE 


FORMAT 


parameters 


KEY 


Associates executable VAXTPU code with a key or a combination 
of keys. 


DEFINE_KEYr 


string 1 

buffer 

range 

program 

learn 


, keywordI,string2l,string3]j) 


string 1 

A string that specifies the VAXTPU statements that are associated with a key. 

buffer 

A buffer that contains the VAXTPU statements that are associated with a key. 

range 

A range that contains the VAXTPU statements that are associated with a key. 

program 

A program that contains the executable code that is associated with a key. 

learn 

A learn sequence that specifies the executable code that is associated with a 
key. 

keyword 

A VAXTPU keyname for a key or a combination of keys. Table 3-5 lists the 
VAXTPU ke 3 mames for the VTIOO and VT200 series of keyboards. You can 
also display the full list of VAXTPU keywords with the built-in procedure 
SHOW (KEYWORDS). 

See the DESCRIPTION section of this built-in procedure for information on 
keys that you cannot define. 

To define a key for which there is no VAXTPU keyname, use the 
built-in procedure KEY_NAME to create your own keyname for the key. 

For example, KEY-NAME ('A', SHIFT-KEY) creates a keyname for the 
combination of PFl, the default shift key for VAXTPU and the keyboard 
character 'A'. For more information, see the description of the built-in 
procedure KEY-NAME. 

string2 

An optional string that is associated with a key that you define. It is treated as 
a comment that can be retrieved with the built-in procedure LOOKUP—KEY. 
You might want to use the comment if you are creating a help procedure for 
keys that you have defined. 
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Strings 

Specifies a key map or a key-map list in which the key is to be defined. If 
a key-map list is specified, the key is defined in the fimt key map in the 
key-map list. If neither a key map nor a key-map list is specified, the key 
is defined in the first key map in the key-map list bound to the current 
buffer. See the descriptions of the built-in procedures CREATE _KEY_MAP, 

CREATE_KEY_MAP_LIST, and SET (KEY_MAP_LIST_) for more 

information on key maps and key-map lists. 


DESCRIPTION The built-in procedure DEFINE _KEY compiles the first parameter if it is a 

string, buffer, or range. 

If you use DEFINE _KEY to change the definition of a key that was previously 
defined, VAXTPU does not save the previous definition. 

You can define all keys on the VTIOO and VT200 keyboards and keypads 
with the following exceptions: 

• The COMPOSE CHARACTER key on VT200 keyboards 

• The ESCAPE key 

• The SHIFT keys 

• The keys FI through F5 

• The PFl key —This is the default shift key for the editor. You cannot 
define PFl unless you use the built-in procedure SET (SHIFT-KEY, 
keyword) to define a different key as the shift key for the editor. 

There are some keys and key definitions that you can define but that 
DIGITAL strongly suggests you avoid defining. VAXTPU > does not signal 
an error when you use them as a keyword parameter, but the definitions 
you assign to these key combinations are not executed unless you set your 
terminal in special ways at the DCL level: 

• CTRL/C, CTRL/O, CTRL/X, and F6—To execute programs that you bind 
to these keys, you must first enter the DCL command SET TERMINAL 
/PASTHRU. 

• CTRL/T, CTRL/Y—To execute programs that you bind to these keys, you 
must first enter the DCL command SET TERMINAL/PASTHRU and/or 
the DCL command SET NOCONTROL. 

• CTRL/S, CTRL/Q—To execute programs that you bind to these keys you 
must first enter the DCL command SET TERMINAL/NOTTSYNC. 

DIGITAL does not recommend that you use these special terminal settings. 
The settings may cause unpredictable results if you do not understand all the 
implications of changing the default settings for giving the terminal driver 
control. 
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RETURN 

STATUS 


TPU$_NOTDEFINABLE 

WARNING 

TPU$_RECURLEARN 

WARNING 

TPU$_NOKEYMAP 

WARNING 

TPU$_NOKEYMAPLIST 

WARNING 

TPU$_KEYMAPNTFND 

WARNING 

TPU$_EMPTYKMLIST 

WARNING 


Second argument is not a valid 
reference to a key. 

This key definition was used as a part 
of a learn sequence. You cannot use it 
in this context. 

Fourth argument is not a defined key 
map. 

Fourth argument is not a defined 
key-map list. 

The key map listed in the fourth 
argument is not found. 

The key-map list specified in the fourth 
argument contains no key maps. 


EXAMPLES 

□ DEFINE_KEy ('POSITION (main_window)•, CTRL.B.KEY) 

This Statement associates the VAXTPU statement POSITION (main—window) 
with the key combination CTRL/B. Note that you must use quotes around 
the VAXTPU statement. 

2 DEFINE_KEY (main.buller, KEY.NAME (PF4, SHIFT.KEY), "mainbuf") 

This Statement causes VAXTPU to compile the main buffer (containing 
VAXTPU statements). If there are no errors in the compilation, VAXTPU 
binds the executable code to the combination of the editor's shift key (PFl by 
default) and PF4 on the keypad. The final string in the statement, "mainbuf" 
is a comment that is associated with the key combination. 

B DEFINE_KEY ('COPY.TEXT ("Ejctenaible")', KEY.NAME (’z*. SHIFT.KEY)) 

This Statement causes VAXTPU to make a copy of the word "Extensible" 
at the current character location in the current buffer, when you press the 
key combination PFl (VAXTPU's default shift key) and z. Notice that you 
must alternate the quote characters that are used as delimiters for the first 
parameter. Also notice that you must quote the keyboard character that you 
use in combination with the editor's shift key. 

Q SAMPLE PROCEDURE 


The following procedure prompts the user for the VAXTPU statements that 
are to be bound to the key that the user specifies. 

PROCEDURE user.del Ine.key 

dal READ_LINE ('Delinition; '); 

kay READ.LINE ('Prasa kay to dafina.'.l); 

IF LENGTH (kay) > 0 

THEN kay :> KEY.NAME (kay) 

ELSE kay LAST.KEY; 

ENDIF; 

DEFINE.KEY (dal.kay); 

ENDPROCEDURE 
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S SAMPLE PROCEDURE 


The following procedure changes the mode of text entry from insert to 
overstrike, or from overstrike to insert. 

PROCEDURE us«r_change.mode 

I Toggle nod« between Insert and overstrike 
IF GET.IMFO (CORRENT_BUFFER, "node") • OVERSTRIKE 
THEN SET (INSERT, CURRENT.BUFFER); 

ELSE SET (OVERSTRIKE, CURRENT.BUFFER ); 

ENDIF; 

!Tbe following statement binds this procedure to the 
Ikey combination CTRL/A. This emulates the VAX/VMS key binding 
■that toggles between Insert and overstrike for text entry 
Iin command line editing. 

DEFINE.KEY Cuser.change.mode', CTRL_A_KEY); 

ENDPROCEDORE; 

S DEFINE_KEY ('MESSAGE ("Hello VAXTPU user")', CTRL.A.KEY, "Greeting", "TPU$KEy_MAP"); 

This example defines a key in a key map. The DEFINE _KEY statement 
defines CTRL/A in the key map TPU$KEY_MAP such that VAXTPU displays 
the message 'Hello VAXTPU user" when CTRL/A is pressed. 

Q DEFINE_KEY ('POSITION (MESSAGE.WINDOW)*, F20,, "novement_map") 

This example uses a key map ("movement_map"), but does not include a 
comment in the optional third parameter. Note the extra comma after the 
keyword F20 in the second parameter. 
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DELETE 


FORMAT 


parameters 


Removes VAXTPU structures from your editing context. When you 
delete a structure, (for example, a range), all variables that refer to 
that structure are reset to UNSPECIFIED. If the deleted structure 
had any associated resources, these resources are returned to the 
editor. 


DELETE 


buffer 

marker 

process 

program 

range 

window 




buffer 

The buffer you want to delete. Any ranges or markers that point to this 
buffer, any subprocess that is associated with this buffer, the memory for 
the buffer control structure, the pages for storing text, and the memory for 
ranges and markers associated with the buffer are deleted also. If the buffer 
is associated with a window that is mapped to the screen, the window is 
unmapped. 

marker 

The marker you want to delete. The memory for the marker control structure 
is deleted also. 

process 

The process you want to delete. The memory for the process control structure 
and the subprocess is deleted also. 

program 

The program you want to delete. The memory for the program control 
structure and the memory for the program code are deleted also. 

range 

The range that you want to delete. The memory for the range control 
structure is deleted also. The text in a range does not belong to the range. 
Rather, it belongs to the buffer in which it is located. A range is merely a way 
of manipulating sections of text within a buffer. When you delete a range, the 
text delimited by the range is not deleted. See the built-in procedure ERASE 
for a description of how to remove the text in a range. 

window 

The window you want to delete. Along with the window, the memory for the 
window control structure and the record history associated with the window 
are deleted. If you delete a window that is mapped to the screen, VAXTPU 
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unmaps the window before deleting it. The screen appears just as it does 
when you use the built-in procedure UNMAP. 


DESCRIPTION 

Depending upon how many variables are referencing an entity, or how many 
other entities are associated with the entity you are deleting, processing the 
built-in procedure DELETE can be time-consuming. 


Any variables that reference the deleted entity are set to UNSPECIFIED and 
all other entities that are associated with the deleted entity are also deleted. 
Use the built-in procedure DELETE with caution. 

RETURN 

STATUS 

For a buffer: 

TPUS—INVBUFDELETE WARNING You are trying to delete a buffer that is 

set as PERMANENT. 

For a line or character; 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

EXAMPLES 


□ DELETE (■aln.buller) 

This command deletes the main buffer and any associated resources that 
VAXTPU allocated for the main buffer. As a result of this command, the 
SHOW (BUFFERS) command does not list main—buffer as one of the buffers 
in your editing context. 

Q SAMPLE PROCEDURE 

The following procedure writes the contents of extra_buf to a file (because 
you do not specify a file name, the associated file for the buffer is used) and 
then removes the extra window and buffer from your editing context. You 
must have previously created these structures and added them to your editing 
context in order for this procedure to execute successfully. 


PROCEDURE user.delete.extra 

WRITE_FILE (extra_bul); 

DELETE (extra.window); 

DELETE (extra.bul); 

! Return the 11 lines from extra.wlndow to the main window 

ADJUSI.WINDOW (main.window. -11. 0); 

ENDPROCEDURE 
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EDIT 


FORMAT 

parameters 


Modifies a string according to the keywords you specify. EDIT is 
similar, although not identical to the DCL lexical function F$EDIT. 
Differences between the built-in procedure and the lexical function 
are noted in the DESCRIPTION section. 


EDIT (string, keyword 1[,..[,keyword2]) 


string 

A quoted string, or an expression that evaluates to a string, that you want to 
modify. 

keyword 1 

You can specify any number of the following keywords: 

• COLLAPSE—Removes all spaces and tabs. 

• COMPRESS—Replaces multiple spaces and tabs with a single space. 

• TRIM—Removes leading and trailing spaces and tabs. 

• TRIM-LEADING—Removes leading spaces and tabs. 

• TRIM—TRAILING—Removes trailing spaces and tabs. 

• UPPER—Converts all lowercase characters to uppercase. 

• LOWER—Converts all uppercase characters to lowercase. 

• INVERT—Changes the current case of the specified characters; uppercase 
characters become lowercase, and lowercase characters become uppercase. 

If you specify more than one of the TRIM keywords (TRIM, 

TRIM—LEADING, TRIM—TRAILING), all of the TRIM operations you specify 
are performed. 

If you specify more than one of the case conversion keywords (UPPER, 
LOWER, INVERT), the last keyword that you specify determines how the 
characters in the string are modified. 

keyword2 

You can specify ON or OFF as optional final parameters: 

• ON—Turns on the recognition of quotation marks or apostrophes as 
VAXTPU quote characters (this is the default). 

• OFF—Turns off the recognition of quotation marks or apostrophes as 
VAXTPU quote characters. 
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DESCRIPTION The string that you specify as the first parameter is modified in place. This 

built-in procedure does not return a result. 

By default, EDIT does not modify quoted text that occurs within a string. For 
example, the following command: 

EDIT ('HE SANG ‘WELL”', LOWER) 

does not change the case of WELL. The string is output as follows: 

h« sang ’WELL" 

If the string you specify has an opening quote, but not a closing quote, the 
status TPU$_MISSINGQUOTE is returned. All text starting at the unclosed 
opening quote and continuing to the end of the string is considered to be part 
of the quoted string and is not modified. 

You can disable the recognition of quotation marks and apostrophes as 
VAXTPU quote characters (this is the default) by using the ke)rword OFF as 
the final parameter for the built-in procedure EDIT. The keyword OFF causes 
the quote characters to be treated as normal text. 

EDIT is similar to the DCL Lexical Function F$EDIT. However, you should 
note the following differences: 

• EDIT modifies the characters in place while F$EDIT returns a result. 

• EDIT takes keywords as parameters while F$EDIT requires that the edit 
commands be specified by a string. 


RETURN 

STATUS 


TPU$—MISSINGQUOTE ERROR Character string is missing a terminating 

quote. 


EXAMPLES 

D 

The following statements edit the string 'PRODUCT NAME' by changing it to 
lowercase, and display the edited string in the message window. 

pn ;« 'PRODUCT NAME'; 

EDIT (pn. LOWER); 

MESSAGE (pn); 

Q SAMPLE PROCEDURE 


The following procedure shows a generalized way of changing any input 
string to lowercase. 

PROCEDURE aa«r_«dlt_Btrlng (Input.atrlng) 

Is ;> Input.string; 

EDIT (is, LOWER); 

MESSAGE (is); 

ENDPROCEDURE 

After compiling the preceding procedure, if you enter the following, after the 
appropriate prompt from your editing interface: 

user.sdit.string ("ZEPHYR") 

the word "zephyr" would be printed in the message area in lowercase. 
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END_OF 

Returns a marker that points to the last character position in a buffer 
or a range. 

FORMAT 

marker := END_OF (/ 1 ) 

( range j 

parameters 

buffer 

The buffer whose last character position you want to mark. 


range 

The range whose last character position you want to mark. 

DESCRIPTION 

If you use the marker returned by this built-in procedure as a parameter for 
the built-in procedure POSITION, your current character position is at this 
marker. 

EXAMPLES 


□ the.end :« END.OF (CURRENT.BUFFER) 

This assignment statement stores the last position in the current buffer in the 
variable the—end. 

Q POSITION (END.OF (deleta.range)) 

This statement uses two built-in procedures to move your current character 
position to the end of delete_range. If delete_range is in a visible buffer in 
which the cursor is located, the cursor position is also moved to the end of 
delete_range. 

g] SAMPLE PROCEDURE 


The following procedure is similar to the edt$paste procedure in the EDT 
Keypad Emulator section file. 

! Alter copying text, append the current line to the last 
! line. An extra blank line is put in the paste bufler 
! during the cut so that a CUT/PASTE of 
! text that has no line terminator works properly. 

! 

PROCEDURE user.paste 
LOCAL paste.text; 

IF (BEGINNING.OF (paste.buffer) <> END.OF (paste.bufler)) 

THEN 

COPY.TEXT (paste.buller); 

APPEND.LINE; 

ENDIF; 

ENDPROCEDURE 
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ERASE 

Removes the contents of the range or buffer that you specify. 

FORMAT 

<{buZ}> 

parameters 

range 

The range whose contents you want to remove. 

buffer 

The buffer whose contents you want to remove. 

DESCRIPTION 

This built-in procedure does not affect the current character position. When 
you erase a buffer, the contents of the buffer are removed. However, the 
buffer structure still remains a part of your editing context and your current 
character position remains in the buffer even if you remove the contents 
of the buffer. The space that was occupied by the contents of the buffer is 
returned to the system and is available for reuse. Only the end-of-buffer line 
remains. 

When you erase a range, the contents of the range are removed from the 
buffer. The range structure is still a part of your editing context. You can 
use the range structure later in your editing session to delimit an area of text 
within a buffer. 

Note: 

Text does not belong to a range; it belongs to a buffer. Ranges are 
merely a way of manipulating portions of text within a buffer. For 
more information, see the description of ranges and markers in Section 2. 


EXAMPLES 


D ERASE (main.buller) 


This command causes the contents of main—buffer to be removed. You 
are left with a buffer named main—buffer, which you can associate with a 
window. 
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Q SAMPLE PROCEDURE 


The following procedure gets rid of embedded carriage-retum/line feed pairs. 


PROCEDURE us«r_reDOV«_crlfa 

0N.ERR0R 

RETURN 

END0N_ERR0R 

erll ASCIKIS) « ASCIKIO); 

LOOP 

cr_range ;• SEARCH (erll, FORWARD, EXACT); 
POSITION (cr.range): 

ERASE (cr.ranga): 

ENDLOOP 


ENDPROCEDURE 
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ERASE- 

CHARACTER 

Deletes the number of characters you specify and optionally returns 
a string that represents the characters you deleted. 

FORMAT 

Estring ERASE.CHARACTER (integer) 

parameter 

integer 

The signed (+/“) integer value that indicates how many characters you want 
to erase. If the integer is greater than 0, VAXTPU removes characters starting 
with the current character and moves toward the end of the line. If the 
integer is less than 0, VAXTPU removes characters starting with the character 
preceding the current character (the current character is not erased) and 
moves toward the beginning of the line. 

QE3CRIPTION erased characters are optionally returned in a string in the order in which 

they appeared on the line. 

Character erasure does not cross line boundaries. 

EXAMPLES 

D taka.out.cbars 

:• ERASE.CHARACTER (10) 


This assignment statement removes the current character and the 9 characters 
following it and stores them in the variable take—out—chars. 

Q prev.chars ;• ERASE.CHARACTER (-E) 

This assignment statement removes the five characters preceding the current 
character and stores them in the variable preu—c/iars. 

g] SAMPLE PROCEDURE 


The following procedure is similar to the procedure the EDT Keypad Emulator 
section file uses to delete characters. 

PROCEDURE U8er_d«late_llke_edteiii 
uv.del*t«d_cbar ;• ERASE.CHARACTER(1); 

IF uv_dal«t«d_ehar • 

THEN 

M0VE_H0RIZ0NTAL(1); 

IF MARK (NONE) <> END.OF (CURRENT_BUFFER) 

THEN 

uv.dalatad.char :« ASCII (10); 

APPEND_LINE: 

ELSE 

M0VE_H0RIZ0NTAL (-1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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ERASE.LINE 


Removes the current line from the current buffer. ERASE_LINE 
optionally returns the line you remove in a string data type. 


FORMAT [string :=| ERASE_LINE 


parameters None. 


DESCRIPTION The line that you erase can be stored in a string. If the line that you remove 

is visible on the screen, it is removed from the screen as well as from the 
buffer. 


EXAMPLES 

Q ERASE_LINE 

This assignment statement removes the current line in the current buffer. 

Q take.out.llne := ERASE.LINE 

This command removes the current line in the current buffer and stores the 
string of characters representing that line in the variable name take—out—line. 


Q SAMPLE PROCEDURE 


The following procedure is similar to the procedure that the EDT Keypad 
Emulator section file uses to delete lines. 

PROCEDURE usar.delete.llne ! delete line 

IF CURRENT.OFFSET = 0 
THEN 

uv_deleted_line :■ ERASE.LINE + ASCII (10); 

ELSE 

UT_deleted.llne ERASE.CHARACTER 

(LENGTH (CURRENT_LINE)) 

+ ASCII (10): 

MOVE_VERTICAL (1); 

IF MARK (NONE) <> END.OF (CURRENT.BUFFER) 

THEN 

APPEND_LINE 

ELSE 

M0VE_H0RIZ0NTAL (-1) 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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EXECUTE 


Does one of the following: 

• Executes programs that you have previously compiled. 

• Compiles and then executes any executable statements in a 
buffer, a range, or a string. 

• Replays or executes a learn sequence. 


FORMAT 


EXECUTE (< 


program 

buffer 

range 

string 

learn 




parameters program 

The program that you want to execute. 

buffer 

The buffer that you want to execute. 

range 

The range that you want to execute. 

String 

The string that you want to execute. 

learn 

The learn sequence that you want to replay. 


DESCRIPTION EXECUTE performs different actions depending upon the data type of the 

parameter. 

If the parameter is a string, or the contents of a buffer or range, it must 
contain only valid VAXTPU statements. Otherwise, you get an error 
message and no action is taken. See the description of the built-in procedure 
COMPILE for restrictions and other information on compiling strings, or the 
contents of a buffer or range. When you pass a string to EXECUTE, the string 
cannot be longer than 132 characters. 

Procedures are usually executed by entering the name of a compiled 
procedure after the appropriate prompt from your editing interface, or by 
calling the procedure from within another procedure. However, it is possible 
to execute procedures with the built-in procedure EXECUTE if the procedure 
returns a data type that is a valid parameter. 
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In the following example, the procedure test returns a program data type. 

If you execute a buffer or range that contains the following code, VAXTPU 
compiles and executes the procedure test, a program data type is returned, the 
program is then used as the parameter for the built-in procedure EXECUTE, 
and the string "abc" is written to the message area: 

PROCEDURE tast 

! Attar conplllng the string 'MESSAGE (■abe”)', 

! VAXTPU ratums a program that is compilad loro 
! of the string. 

RETURN COMPILE (’MESSAGE ("abc")'); 

ENDPROCEDURE 

! The built-in procadora EXECUTE executas the 
! program ratumad by the procedure tast. 

EXECUTE (TEST) 


RETURN 

STATUS 

For a learn sequence; 

TPU$_NODEFINITION 

WARNING 

There is no definition for this key. 


TPU$_REPLAYWARNING 

WARNING 

Inconsistency during the execution of a 
learn sequence . . . proceeding. 


TPU$_REPLAYFAIL 

WARNING 

Inconsistency during the execution of a 
learn sequence . . . execution stopped. 


TPU$_CONTROLC 

ERROR 

The execution of the command 
terminated because you pressed 
CTRL/C. 


For a string: 

TPU$_EXECUTEFAIL 

WARNING 

Execution of the indicated item has 
halted because it contains error. 






EXAMPLES 


EXECUTE (user.progran) 


This command executes the executable statements in the program named 
user_program. 


Q EXECUTE (main_buffer) 


This command first compiles the contents of main—buffer and then executes 
any executable statements. If you have any text in the main buffer other 
than VAXTPU statements, you get an error message. If there are procedure 
definitions in main_buffer, they are compiled, but they are not executed 
until you run the procedure (either by entering the procedure name after 
the appropriate prompt from your interface or by calling the procedure from 
within another procedure). 

B SAMPLE PROCEDURE 


The following procedure prompts the user for a VAXTPU command to execute 
and then executes the command. 

PROCEDURE user.do 

commaiid_strliig :» READ .LINE ("Enter VAXTPU command to execute; ”); 

EXECUTE (Command_8trlng); 

ENDPROCEDURE 
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Q SAMPLE PROCEDURE 


The following procedure executes a command with informational messages 
turned on, and then turns the informational messages off after the command 
is executed. You must provide the actual parameter (VAXTPU statement) for 
the formal parameter tpu_command. 

PROCEDURE usar.tpu (tpu.eoBmand) 

SET (INFORMATIOHAL, ON); 

EXECUTE (tptt_C0BBand); 

SET (INFORMATIONAL, OFF); 

ENDPROCEDURE 
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EXIT 

Terminates the editing session and writes out any modified buffers 
that have associated files. VAXTPU queries you for file names for 
any buffers that you have modified that do not already have an 
associated file. 

Buffers that have the NO_WRITE attribute are not written out. See 
SET (NO-WRITE, buffer). 

FORMAT 

EXIT 

parameters 

None. 

DESCRIPTION 

If you do not modify a buffer, VAXTPU does not write out the next version of 
the file associated with the buffer when you use the built-in procedure EXIT 
to exit from VAXTPU. 

If you modify a buffer that does not have an associated file name, 

(because you did not specify a file name for the second parameter of 
CREATE—BUFFER), VAXTPU asks you to specify a file name if you want 
to write the buffer. If you press the RETURN key rather than entering a 
file name, the modified buffer is discarded. VAXTPU queries you about all 
modified buffers that do not have an associated file name. The order of the 
query is the order in which the buffers were created. 

If an error occurs while you are trying to exit, the exit is halted and control 
returns to the editor. 

RETURN 

STATUS 

TPU$_EXITFAIL WARNING The EXIT did not complete successfully 

due to problems writing modified 
buffers. 

EXAMPLE 



EXIT 


This command ends the editing session and writes out any modified buffers 
that have an associated file name. If you have modified a buffer that does 
not have an associated file name, VAXTPU queries you with the following 
prompt: 

Enter a file name to write buffer BUFFER.NAME; elae preaa RETURN: 

The term BUFFER—NAME is replaced with the name of your buffer. Enter a 
file name, such as text_file.lis if you want the contents of the buffer written 
to a file. Press the RETURN key if you do not want to write the contents of 
the buffer to a file. 
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EXPAN D_N AM E 


Returns a string that contains the name or names of any VAXTPU 
variables, keywords, or procedures (built-in or user-written) that 
begin with the string that you specify. VAXTPU searches its internal 
symbol tables to find a match, using your input string as the initial 
substring for the match. 






FORMAT string2 := EXPAND_NAME (string 1, keyword) 
parameters string 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the initial substring of a VAXTPU 
name. 

keyword 

The type of VAXTPU name you want to match. The valid keywords are the 
following: 

• ALL—Matches all names. 

• PROCEDURES—Matches only procedure names. 

• KEYWORDS—Matches only keyword names. 

• VARIABLES—Matches only variable names. 


DESCRIPTION If there are no matches for the substring you specify, a null string is returned 

and a warning (TPU$_NONAMES) is signaled. If only one VA>ftPU name 
matches the substring you specify, the word is returned with no trailing space. 
If more than one VAXTPU name matches your substring, all of the matching 
names are returned. The matching words are returned as a concatenated 
string with each word separated by a single space. Multiple names signal a 
warning (TPU$_MULTIPLENAMES). 

You can use EXPAND_NAME to write procedures that perform command 
completion or interpret abbreviated names. 


RETURN 

STATUS 


TPU$_NONAMES WARNING 

TPU$_MULTIPLENAMES WARNING 


No names were found matching the one 
requested. 

More than one name matching the one 
requested was found. 
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EXAMPLES 

□ lull_naine EXPAND.HAME ('CREATE', ALL) 

If you are using the EDT Keypad Emulator, this assignment statement returns 
the following VAXTPU names in the string full_name: 

CREATE.BUFFER CREATE.PROCESS CREATE.RANGE CREATE.WINDOW 


s SAMPLE PROCEDURE 


The following procedure uses the string that you enter as the actual 
parameter, and puts the expanded form of a valid VAXTPU procedure name 
that matches the string in the message area. If the initial string matches 
multiple procedure names, or if it is not a valid VAXTPU procedure name, an 
explanatory message is written to the message area. 

PROCEDURE U8er_qulck_par8e (abbrevlated.name) 

ON.ERROR 

IF ERROR = TPUt.NONAMES 
THEN 

MESSAGE ("No 8uch procedure.”}; 

ELSE 

IF ERROR • TPU$_MULTIPLENAMES 
THEN 

MESSAGE ("Ambiguoua abbreviation.*); 

ENDIF; 

ENDIF; 

RETURN: 

END0N_ERR0R; 

expanded.nane EXPAND.NAME (abbreviated.name, PROCEDURES): 

MESSAGE ("The procedure i8 " + expauded.name + 

ENDPROCEDURE 
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FAO 


Invokes the Formatted ASCII Output (FAO) system service to 
convert a control string to a formatted ASCII output string. By 
specifying arguments for FAO directives in the control string, 
you can control the processing performed by the $FAO system 
service. The built-in procedure FAO returns a string that contains 
the formatted ASCII output. 

For complete information on the $FAO system service, see the 
VAX/VMS System Services Reference Manual. 


FORMAT string2 := FAO (string 1 [,FAO parameters]) 


parameters stringl 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that consists of the fixed text of the 
output string and FAO directives. 

Some FAO directives that you might want to include as part of the string are 
the following: 

• !AS—Inserts a string as is. 

• !OL—Converts a longword to octal notation. 

• !XL—Converts a longword to hexadecimal notation. 

• !ZL—Converts a longword to decimal notation. 

• !UL—Converts a longword to decimal notation without adjusting for 
negative numbers. 

• !SL—Converts a longword to decimal notation with negative numbers 
converted properly. 

• !/—Inserts a new line (carriage retum/line feed). 

• !_—Inserts a tab. 

• !]—Inserts a form feed. 

• !!—Inserts an exclamation mark. 

• !%S—Inserts an s if the most recently converted number is not 1. 

• !%T—Inserts the current time if you enter 0 as the parameter (you cannot 
pass a specific time because VAXTPU does not use quadwords). 

• !%D—Inserts the current date and time if you enter 0 as the parameter 
(you cannot pass a specific date because VAXTPU does not use 
quadwords). 

FAO parameters 

The FAO parameters are listed in the description of $FAO in the VAX/VMS 
System Services Reference Manual. In general, they correspond to the FAO 
directives in stringl. 
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DESCRIPTION FAO returns a formatted string, constructed according to the rules of the 

$FAO system service. The control string directs the formatting process, and 
the optional arguments are values to be substituted into the control string. 

All strings are given via the !AS directive. 


RETURN 

STATUS 


TPUS—INVFAOPARAM WARNING Argument was not a string or integer. 


EXAMPLES 

Q date_and_tlme :• FAO (”!XD",0) 

This assignment statement stores the current date and time in the variable V—/ 

name date^nd—time. 

Q SAMPLE PROCEDURE 

The following procedure uses the FAO directive !SL in a control string to 
convert the number equated to the variable count to a string. The converted 
string is stored in the variable report and then is written to the message area. 

PROCEDURE nser.fao.conTorsion 
count :• 67; 

report := FAO ("number oi forms » !SL", count); v , 

MESSAGE (report); 

ENDPROCEDURE 

g] SAMPLE PROCEDURE 


The following procedure formats the message that is being written to the 
message area. The message tells the user the line and column at which an 
error occurred. 

PROCEDURE user.error.message (stmg, line, col) 
error.count := error.count + 1; 

MESSAGE (FAO (MAS at line !UL column !UL', stmg, line, col)); 
ENDPROCEDURE 
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FILE__PARSE 


Performs the equivalent of the DCL F$PARSE lexical function. That 
is, it calls the RMS service SPARSE to parse a file specification and 
to return either an expanded file specification or the file specification 
field that you request. 

FILE_PARSE returns a string that contains the expanded file 
specification or the field you specify. If you do not provide a 
complete file specification, FILE_PARSE supplies defaults in the 
return string, as described in the DESCRIPTION section. 

If an error occurs during the parse, FILE_PARSE returns a null string. 


FORMAT string4 := 

FILE-PARSE (string 11[,string21[,string3l[,keyword]l]l]l) 


parameters string 1 

The file specification to be parsed. 

string2 

A default file specification. Any field of the file specification that you provide 
with this parameter is substituted in the output string if that field is missing 
in the file specification. 

Strings 

A related file specification. Some of the fields in the related file specification 
are substituted in the output string if a field is missing from both the file 
specification and the default specification parameters. 

keyword 

A field in a VAX/VMS file specification. Following is a list of the valid 
keywords: 

• NODE 

• DEVICE 

• DIRECTORY 

• NAME 

• TYPE 

• VERSION 
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DESCRIPTION The built-in procedure FILE—PARSE allows you to parse file specifications 

using the RMS service SPARSE. For more information on the SPARSE 
routine, see the VAX Record Management Services Reference Manual. 

Specify the first three parameters as strings. The fourth parameter is a 
keyword. Logical names and device names must terminate with a colon. If 
you omit optional parameters to the left of a parameter, you must include 
null strings as place holders for the missing parameters. 

If you omit the file name, file type, or version number, FILE—PARSE supplies 
defaults, first from string2 and then from stringS. If you do not provide 
names with these parameters, FILE—PARSE returns a null specification for 
these fields. 

Wildcards can be used. 


RETURN 

STATUS 


TPU$_PARSEFAIL WARNING An error was detected by RMS while 

parsing file-specification. 


EXAMPLES 

D spec := FILE.PARSE (' progrtun. pas', '[abbott]') 

This assignment statement calls RMS to parse and return a full file 
specification for the file program.pas. The second parameter provides the 
name of the directory in which the file can be found. 

Q SAMPLE PROCEDURE 


The following procedure starts journaling. It is called from the 
tpu$init—procedure after a file is read into the current buffer. FILE—PARSE is 
used to return the full file spec for the journal file. 

PROCEDURE user.start.journal 
! Default journal name 
LOCAL default_joumal_name, 

! Auxiliary journal name derived from file name 
aux_ j oumal.name; 
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IF (GET.INFO (COMMAND_LINE, "Journal") - 1) AND 
(GET.INFO (COMMAND.LINE, "read_only") <> 1) 

THEN 

aux_]oumal_na]ie :• GET_INF0 (CURRENT.BUFFER, ”flla_name"); 

IF anx_Joumal_na]na » 

THEN 

aux_joumal_namo :• GET.INFO (CDRRENT.BOFFER, "output.llla"); 

ENDIF; 

IF aux_Joumal_naoe • 0 
THEN 

aux_joumal_naaia :■ 

ENDIF; 

IF aux_joumal_naiiie • 

THEN 

default_Joumal_name ;■ "uaar.TJL”; 

ELSE 

delault_joumal_na]ne ;• ".TJL”; 

ENDIF; 

Joumal_me GET.INFO (COMMAND.LINE. "Joumal.fila"); 
joumal.file :• FILE.PARSE (joumal.file, default.Joumal.na]ne, 

aux.Joumal.nama}; 

JOURNAL.OPEN (Joumal.file); 

ENDIF; 

ENDPROCEDURE 
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FILE-SEARCH 


Calls the RMS service $SEARCH to search a directory file and return 
the full file specification for the file that you specify. 


FILE-SEARCH returns a string containing the resulting file 
specification. If the file is not found in the directory, FILE—SEARCH 
returns a null string and signals an error. 

FORMAT 

string2 := FILE-SEARCH (stringl) 

parameter 

string 1 

The file specification you want to find. If you omit the device or directory 
names, FILE—SEARCH supplies defaults from your current default device and 
directory. FILE—SEARCH does not supply defaults for a file name or type. 

DESCRIPTION 

The built-in procedure FILE—SEARCH allows you to search for files in a 
directory using the $SEARCH routine. You have to use this built-in procedure 
multiple times with the same parameter to get all of the occurrences of a file 
name in a directory. See the VAX Record Management Services Reference 
Manual for more information on $SEARCH. 

RETURN 

STATUS 

TPU$_SEARCHFAIL WARNING File specified by 'string' argument was 

not found. 


TPU$_PARSEFAIL WARNING An error was detected by RMS while 

parsing file-specification. 


EXAMPLES 

D m ;• FILE_SEARCH (■SYStSYSTEM:*.EXE') 


Each time this assignment statement is executed, it returns a string containing 
the resulting file specification of an EXE file in SYS$SYSTEM. Because no 
version number is specified, only the latest version is returned. When you get 
a null string, it means there are no more EXE files in the directory. 
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Q SAMPLE PROCEDURE 



This procedure puts each RNO file that is in the current directory into its own 
buffer. You can use the SHOW (BUFFERS) statement to display the buffers 
created with this procedure. 

PROCEDURE U8«r_coll*ct_rnos 
LOCAL 

lll«.ap«c :■ riLE.SEARCH (•’): 

LOOP 

fll«_sp«c FILE_SEARCH ('•.RNO'): 

EXITIF file.spac = 

CREATE_BUFFER (FILE.PARSE (llle.apec, NAME), 

flle.apec); 

ENDLOOP 

ENDPROCEDURE 

The assignment statement following the LOCAL statement sets the variable 
file—spec to a null string. It is important to clear the variable of any values 
that might be stored there from a previous FILE—SEARCH operation. 
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FILL 

Reformats the text in the specified buffer or range so that the lines 
of text are approximately the same length. 

FORMAT 

FILL ([ ], String[Jntegerl [Meger2B) 

( range j 

parameters 

buffer 

The buffer whose text you want to fill. 


range 

The range whose text you want to fill. 


String 

The characters that you want to use as word separators when filling the text 
in a buffer. 


integerl 

The value for the left margin. The left margin value must be at least 1, and 
less than or equal to the right margin value. 


integer2 

The value for the right margin. The right margin value cannot exceed the 
maximum record size for the buffer. 

DESCRIPTION 

When filling text, VAXTPU breaks lines at the last word separator before 
the right margin. Some characters commonly used as word separators are 
the space character, horizontal tab, line feed character, vertical tab, form 
feed, and carriage return. When editing programs, you might want to specify 
parentheses, angle brackets, quotation marks, and so on as word separators. 


If you want to specify a control character as a word separator, there are two 
ways to enter control characters in VAXTPU: 

1 You can use the built-in procedure ASCII with the decimal value of the 
control character that you want to enter. For example, COPY-TEXT 
(ASCII (27)) causes the escape character to be entered in the current 
buffer. 

2 You can use the special functions provided by EVE or EDT Keypad 
Emulator to enter control characters. (See Section 3.2.1 for information on 
entering control characters with the interface you are using.) 

VAXTPU takes out spaces and tab characters from the beginning and end 
of lines of text. Line terminators, such as carriage returns, are replaced with 
spaces and new line terminators are added in place of spaces when necessary. 
Trailing spaces on a filled line are deleted. 
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If you do not specify values for the optional margin settings, VAXTPU uses 
the margin values for the buffer when filling the text in the buffer. (The 
default value for the left margin is 1, and the default value for the right 
margin is 80. You can change the margin setting for the buffer with the 
built-in procedure SET (MARGINS, .. . ). Both margin settings must be 
greater than 0.) 


RETURN 

STATUS 


TPU$_BADMARGINS 

TPU$_NEEDTERMS 


WARNING Left margin must be greater than right 
and both must be greater than zero. 

ERROR You must specify characters at which 
breaks in text are desired. 


EXAMPLES 

□ FILL (CURRENT.BUFFER. ' ') 






When entering this statement, press the space bar between the quote 
characters to cause the space character to be used as a word separator. 

This statement reformats the text in the current buffer so that the lines 
are approximately the same length, the space character is used as a word 
separator. 

S FILL (my.bulfer, ASCIKIS) + ASCII(IO), 6, 66) 

This statement fills the buffer my—buffer using the carriage return and line 
feed characters as word separators, and spacing the text between a left margin 
of 5 and a right margin of 65. 
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GET_INFO 

Provides information about the current status of your editing 
context. See Table 4-1 and Table 4-2 for a list of the information 
that GET_INFO returns. See also the description of the built-in 
procedure SHOW. 


FORMAT 

return—value := 

GET INFO d Parameter 1 ,parameter2 I. 

\ parameter!,parameter2,parameters ] 

w 

parameters 

parameter 1 

Either a variable representing a VAXTPU data type or a keyword. GET_INFO 
provides information about the item specified as parameter 1. Table 4-1 lists 
the return values when a variable is used for parameter 1. Table 4-2 lists the 
return values when a ke)rword is used for parameter 1. 



parameter2 

A quoted string, a variable name, or an expression that evaluates to one of 
the string constants in Table 4-1 or Table 4-2. The string used as parameter2 
indicates the kind of information requested about the item in parameter 1. 

You can enter the string in uppercase or lowercase characters. 

w 


parameters 

A quoted string, a variable name, or an expression that evaluates to the 
name of either a key map or a key-map list. Parameters is valid only when 
parameterl is the keyword DEFINED_KEY or the keyword KEY_MAP. 



DESCRIPTION Depending upon the kind of information requested, GET_INFO returns any 

one of the following: 


• A string 

• An integer (A true or false value is returned as 1 or 0, respectively) 

• A buffer 

• A window 

• A range 

• A marker 

• A process 

• A keyword 

w 
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Table 4-1 GET_INFO - Using a Variable as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 

Any VAXTPU variable 

'type' 

Keyword 

Data type of item 

A buffer variable 

"character" 

String 

Character at the current character 
position 


"file_name" 

String 

Name of a file given as the second 
parameter to CREATE—BUFFER; 
null if none was specified 


'first—marker" 

Marker or Integer 0 

First marker in VAXTPU's internal 
list of markers, 0 if none 


"first-range" 

Range or Integer 0 

First range in VAXTPU’s internal 
list of ranges, 0 if none 


"line" 

String 

Line of text at current character 
position 


"map-COunt" 

Integer 

Number of windows associated 
with the buffer 


"modified" 

Integer (1 or 0)’ 

Value that indicates whether the 
buffer has been modified 


'name' 

String 

Name given buffer when it was 
created 


"next—marker" 

Marker or Integer 0 

Next marker in VAXTPU's internal 
list of markers, 0 if no more 


"next—range' 

Range or Integer 0 

Next range in VAXTPU's internal 
list of ranges, 0 if no more 


"offset" 

Integer 

Offset of current character 
position from the beginning of 
the line 


"offset—column' 

Integer 

Screen column that the current 
character position would occupy if 
it were on the screen, unshifted 


‘record—count" 

Integer 

Number of records (lines) in the 
buffer 


"record—size" 

Integer 

Maximum length for records (lines) 
in the buffer 


The following items are established or changed with the built-in 
procedure SET. 


"direction" 

Keyword 

FORWARD or REVERSE 


"eob—text' 

String 

String representing the end-of- 
buffer text 


"key-map-list" 

String 

Key-map list that is bound to the 
buffer 


"left—margin" 

Integer 

Current left margin setting 


^ An integer value of 1 indicates True and an integer value of 0 indicates False. 
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Table 4-1 (Cent.) GET_iNFO - Using a Variable as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 



“max_lines” 

Integer 

Maximum number of records 
(lines) in the buffer 



"mode" 

Keyword 

INSERT or OVERSTRIKE 



"no_write" 

Integer d or 0)’ 

Value that indicates whether the 
buffer (if modified) should be 
output to a file upon exit 



"output—file" 

String or Integer 0 

The name of the file used with 
the built-in procedure SET 
(OUTPUT-FILE_) 



"permanent" 

Integer (1 or Op 

Value that indicates whether the 
buffer is permanent or if it can be 
deleted 



"right—margin" 

Integer 

Current right margin setting 



"system" 

Integer (1 or 0)^ 

Value that indicates whether the 
buffer is a system buffer 



"tab—stops" 

String or Integer 

String that represents the values 
(each separated by a single 
space) of tab stops for SET 
(TAB-STOPS, buffer, string); 
integer that is the interval 
between tab stops for SET 
(TAB—STOPS, buffer, integer) 

y 

A marker variable 

"buffer" 

Buffer 

Buffer in which the marker is 
located 



“offset" 

Integer 

Offset of the marker from the 
beginning of the line 



"offset—column" 

Integer 

Screen column that the marker 
would occupy if it were on the 
screen (does not account for 
shifting of text within a window) 

y 


"video" 

Keyword 

Video attribute of the marker 


A process variable 

"pid" 

Integer 

Process identification number 


A range variable 

"buffer" 

Buffer 

The buffer in which the range is 
located 



"video" 

Keyword 

Video attribute of the range 



^ An integer value of 1 indicates True and an integer value of 0 indicates False. 
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Table 4-1 (Cent.) GET—INFO - Using a Variable as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 

A string variable^ 





The following items are established or 
procedure SET. 

changed with the built-in 


‘self-insert’ 

Integer (1 or 0)’ 

Value that indicates whether 
printable characters are to be 
inserted into the buffer if they are 
not defined 


"shift-key" 

Keyword 

Keyword for the key currently 
used as the shift key 


‘undefined—key" 

Program or Integer 0 

Program called when an undefined 
character is entered; 0 if the 
program issues the default 
message 

A window variable 

"beyond—eol" 

Integer (1 or 0)’ 

Value that indicates whether the 
cursor is beyond the end of the 
current line 


"buffer" 

Buffer or Integer 0 

The buffer that is associated with 
the window, 0 if none 


"current—column" 

Integer 

Column in which the cursor was 
most recently located 


"current—row" 

Integer 

Row in which the cursor was 
most recently located 


"next" 

Window or Integer 0 

Next window in VAXTPU's 
internal list j^f windows, 0 if last^ 


"original—bottom' 

Integer 

Screen line number of the bottom 
of the window when it was 
created (does not include status 
line) 


"original—length" 

Integer 

Number of lines in the window 
(includes status line) 


"original—top' 

Integer 

Screen line number of the top of 
the window when it was created 


"previous" 

Window or Integer 0 

Previous window in VAXTPU's 
internal list of windows, 0 if first^ 


"shift—amount" 

Integer 

Number of columns the window is 
shifted to the left 


"visible" 

Integer (1 or 0)’ 

Value that indicates whether 
window is mapped to the screen 
and is not occluded 


^ An integer value of 1 indicates True and an integer value of 0 indicates False. 

^VAXTPU orders windows according to their "original top" line number. If multiple windows have the same 
top line number, the most recently created window comes first in VAXTPU’s list of windows. 

^The string must identify the name of either a key map or a key-map list. 
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Table 4-1 (Cont.) GET_INFO - Using a Variable as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 


“visible-bottom' 

Integer 

Screen line number of the visible 
bottom of the window (does not 
include status line) 


“visible-length" 

Integer 

Visible length of the window 
(includes status line) 


“visible—top" 

Integer 

Screen line number of the visible 
top of the window 


The following items are established 
procedure SET. 

or changed with the built-in 


“blink—status' 

Integer (1 or 0)’ 

Value that indicates whether 

BLINK is one of the video 
attributes of the window's status 
line 


“blink_video“ 

Integer (1 or 0)’ 

Value that indicates whether 

BLINK is one of the video 
attributes of the window 


“bold—status' 

Integer (1 or 0)’ 

Value that indicates whether 

BOLD is one of the video 
attributes of the window's status 
line 


“bold—video' 

Integer (1 or 0)’ 

Value that indicates whether 

BOLD is one of the video 
attributes of the window 


“no—video' 

Integer (1 or 0)’ 

Value that indicates whether the 
video attribute of the window is 
NONE 


“no—video—status" 

Integer (1 or 0)’ 

Value that indicates whether the 
video attribute of the window's 
status line is NONE 


“pad" 

Integer (1 or 0)’ 

Value that indicates whether the 
window is blank padded at the 
right 


“reverse_video“ 

Integer (1 or 0)’ 

Value that Indicates whether 
REVERSE is one of the video 
attributes of the window 


“reverse—status' 

Integer (1 or 0)’ 

Value that indicates whether 
REVERSE is one of the video 
attributes of the window's status 
line 


“scroll—amount" 

Integer 

Number of lines to scroll 


“scroll-bottom" 

Integer 

Bottom of the scrolling area - 
this is an offset from the bottom 
screen line 


“scroll-top" 

Integer 

Top of the scrolling area - this is 
an offset from the top screen line 


’An integer value of 1 indicates True and an integer value of 0 indicates False. 
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Table 4-1 (Cent.) GET_IIMFO - Using a Variable as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 


“stalus—line" 

“status—video* 

String or Integer 0 
Keyword or Integer 

Text of status line, 0 if none 

If there is no video attribute 
or only one video attribute 
for the window’s status 
line, the appropriate video 
keyword (NONE, BLINK, BOLD, 
REVERSE, UNDERLINE or 

SPECIAL-GRAPHICS) Is returned; 
if there are multiple video 
attributes for the window's status 


o 



line, the integer 1 is returned. 

(If there is no status line for 
the window, the integer 0 is 
returned.) 


"text" 

Keyword 

Value that indicates which 
keyword was used with SET 
(TEXT, window, keyword) 

o 

"underline—status" 

Integer (1 or 0)’ 

Integer (1 or 0)’ 

Value that indicates whether 
UNDERLINE is one of the video 
attributes of the window's status 
line 

"underline—video" 

Value that indicates whether 
UNDERLINE is one of the video 
attributes of the window 




"video" 

Keyword or Integer 

If there is no video or only one 
video attribute for the window, 
the appropriate video keyword 
(NONE, BLINK, BOLD, REVERSE, 
or UNDERLINE) is returned; if 
there are multiple video attributes 




for the window, the integer 1 is 
returned 


"width" 

Integer 

Width of the window 


^ An integer value of 1 indicates True and an integer value of 0 indicates False. 
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Table 4-2 GET_INFO - Using a Keyword as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 

BUFFERISl 

'current' 

Buffer or Integer 0 

Current buffer, 0 if none 


'first" 

Buffer or Integer 0 

First buffer in VAXTPU's internal list 
of buffers, 0 if none’ 


"last" 

Buffer or Integer 0 

Last buffer in VAXTPU’s internal list 
of buffers, 0 if none’ 


'next'2 

Buffer or Integer 0 

Next buffer in VAXTPU’s internal list 
of buffers, 0 if last’ 


'previous'^ 

Buffer or Integer 0 

Preceding buffer in VAXTPU’s internal 
list of buffers, 0 if first’ 

COMMAND_LINE 

"command" 

Integer (1 or 0)^ 

Value that indicates whether 
/COMMAND was specified when 
invoking VAXTPU 


"command-file" 

String 

File specification for /COMMAND= 


"create" 

Integer (1 or 0)^ 

Value that indicates whether /CREATE 
is active (either by default or because 
/CREATE was specified when invoking 
VAXTPU) 


"display" 

Integer (1 or 0)^ 

Value that indicates whether 
/DISPLAY is active (either by default 
or because /DISPLAY was specified 
when invoking VAXTPU) 


“file_name" 

String 

File specification used as a parameter 
when invoking VAXTPU 


"journal" 

Integer (1 or 0)^ 

Value that indicates whether 
/JOURNAL is active (either by default 
or because /JOURNAL was specified 
when invoking VAXTPU) 


"journal—file" 

String 

File specification for /J0URNAL= 


"output" 

Integer (1 or 0)^ 

Value that indicates whether 
/OUTPUT is active (either by default 
or because /OUTPUT was specified 
when invoking VAXTPU) 


"output-file" 

String 

File specification for /OUTPUT- 


"read-only" 

Integer (1 or 0)^ 

Value that indicates whether 
/READ-ONLY was specified when 
invoking VAXTPU 


"recover" 

Integer (1 or 0)^ 

Value that indicates whether 
/RECOVER was specified when 
invoking VAXTPU 


WAXTPU orders buffers and processes according to the order in which they are created; the first ones 
created are the first in the list. 

^Use string constants 'current', or 'first', before using 'next'. Use 'current' or 'last' before using 
'previous". 

^An integer value of 1 indicates True and an integer value of 0 indicates False. 
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Table 4-2 (Cont.) GET_INFO - Using a Keyword as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Vaiue 


“section' 

Integer (1 or 0)^ 

Value that indicates whether 
/SECTION is active (either by default 
or because /SECTION was specified 
when invoking VAXTPU) 


'section_file“ 

String 

File specification for /SECTION- 

DEBUG 

“local" 

Variable 

First local variable in the previous 
procedure, 0 if there are no more 
local variables. When the return value 
is 0, TPU$_FAILURE is returned. 

When you set the debugging context 
to local, and use the GET_INFO 
parameter DEBUG, the parameters 
“next" and “previous” refer to local 
variables. 


“next" 

Parameter or variable 

Next parameter (or 0 if there are no 
more parameters) when the context is 
set to parameter; next local variable 
(or 0 if there are no more local 
variables) when the context is set to 
local. When the return value is 0, 
TPU$_FAILURE is returned. 


“parameter" 

Parameter 

First parameter of the previous 
procedure, 0 if there are no more 
parameters. When the return value 
is 0, TPU$_FAILURE is returned. 

When you set the debugging context 
to parameter and use the GET_INFO 
parameter DEBUG, the parameters 
“next” and “previous" refer to 
parameters. 


“previous" 

Parameter or variable 

Previous parameter (or 0 if there 
are no more parameters) when the 
context is set to parameter; previous 
local variable (or 0 if there are no 
more local variables) when the context 
is set to local. When the return value 
is 0, TPU$_FAILURE is returned. 

DEFINED_KEY'‘ 

“first" 

Keyword 

Keyword of the first key in the 
specified key map or key-map list 


“last" 

Keyword 

Keyword of the last key in the 
specified key map or key-map list 


^An integer value of 1 indicates True and an integer value of 0 indicates False. 

'‘When Parameterl is DEFINED_KEY the built-in procedure takes a string as a third parameter. The string 
specifies the name of either the key map or key-map list to be searched. 
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Table 4-2 (Cont.) GET_INFO - Using a Keyword as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 


"next"® 

Keyword or integer 0 

Keyword of the next key in the 
specified key map or key-map list, 0 if 
last 


"previous"® 

Keyword or integer 0 

Keyword of the previous key in the 
specified key map or key-map list, 0 if 
first 

KEY_MAP® 

"first" 

String 

Name of the first key map in the 
key-map list 


"last" 

String 

Name of the last key map in the 
key-map list 


"next"® 

String 

Name of the next key map in the 
key-map list 


"previous"® 

String 

Name of the previous key map in the 
key-map list 

KEY_MAP_LIST 

"current" 

String 

Name of the current key-map list 


"first" 

String 

Name of the first key-map list 


"last" 

String 

Name of the last key-map list 


"next"^ 

String 

Name of the next key-map list 


"previous"^ 

String 

Name of the previous key-map list 

PROCESS 

"first" 

Process or Integer 0 

First process in VAXTPU's internal list 
of processes, 0 if none® 


"last" 

Process or Integer 0 

Last process in VAXTPU's internal list 
of processes, 0 if none® 


"next"2 

Process or Integer 0 

Next in VAXTPU's internal list of 
processes, 0 if last® 


"previous"^ 

Process or Integer 0 

Preceding process in VAXTPU's 
internal list of processes, 0 if first® 

SCREEN 

"ansi_crt" 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal is an ANSI—CRT 


“current-column" 

Integer 

Column number of the current column 


"current—row" 

Integer 

Screen line number of the current row 


^Use string constants "current*, or "first", before using "next". Use "current" or "last" before using 
"previous". 

^An integer value of 1 indicates True and an integer value of 0 indicates False. 

®Use string constant "first", before using "next". Use "last" before using "previous". Note that "current" 
is not valid when Parameterl is DEFINED_KEY or KEY_MAP, although it is valid when Parameterl is 
KEY_MAP_LIST. 

®When Parameterl is KEY_MAP, the built-in procedure takes a string as a third parameter. The string 
specifies the name of the key-map list to be searched. 
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Table 4-2 (Cent.) GET-INFO - 

Using a Keyword as Parameterl 

Parameterl Parameter2 

Return Value 

Description of Return Value 

'dec—crt' 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal is a DEC—CRT 

"dec_crt2’ 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal is a DEC_CRT2 

'edit_mode" 

Integer (1 or 0)® 

Value that indicates whether the 
terminal is set to edit mode 

“eightbit' 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal uses eightbit characters 

"line_editing’ 

Keyword or Integer 0 

Current method of line editing (Insert 
or Overstrike), 0 if none. 

'original-Width" 

Integer 

Physical width of the screen when you 
invoked VAXTPU 

'scroll' 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal has scrolling regions, 
DEC-CRT 

'visible-length' 

Integer 

Page length of the terminal 

'width" 

Integer 

Current physical width of the screen 

"vklOO" 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal is a GIGI 

"vtlOO" 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal is in the VT100 series 

'vt200" 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal is in the VT200 series - 
returns true only on VAX/VMS 

Version 4.0 or higher 

The following items are established or changed with the built-in procedure SET. 

"auto-repeat" 

Integer (1 or 0)^ 

Value that indicates whether the 
terminal's auto—repeat feature is on 

"prompt—length" 

Integer 

Number of lines in the prompt area 

"prompt—row' 

Integer 

Screen line number at which the 
prompt area begins 

'screen-update" 

Integer (1 or 0)^ 

Value that indicates whether screen 
updating is turned on 

SYSTEM "display" 

Integer (1 or 0)^ 

Value that indicates whether the 
supported input device is a terminal. 

If the VAXTPU session is running in 
batch mode, 0 is returned 

'journal—file" 

String 

Name of the journal file 

"section—file" 

String 

Name of section file used when 
VAXTPU was invoked 

"update" 

Integer 

Update number of this version of 
VAXTPU 


^An integer value of 1 indicates True and an integer value of 0 indicates False. 
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Table 4-2 (Cont.) GET—INFO - Using a Keyword as Parameterl 


Parameterl 

Parameter2 

Return Value 

Description of Return Value 


"version" 

Integer 

Version number of VAXTPU 


The following items are established or changed with the built-in procedure SET. 


"bell" 

Keyword or Integer 0 

ALL if bell is on for all messages, 
BROADCAST if bell is on for 
broadcast messages only, 0 if SET 
(BELL, . . . ) feature is off 


"facility_name" 

String 

Current facility name 


"informational" 

Integer (1 or 0)^ 

Value that indicates whether SET 
(INFORMATIONAL, . . . ) is on 


"journaling_frequency" 

Integer 

The number that indicates how 
frequently records are written to 
the journal file 


"message-flags" 

Integer 

Current value of message flag setting 


"shift-key" 

Keyword 

Value of the key set with SET 
(SHIFT-KEY) for the current buffer 


"success" 

Integer (1 or 0)^ 

Value that indicates whether SET 
(SUCCESS, . . . ) is on 


"timed-message" 

String 

Text that VAXTPU displays at one 
second intervals in the prompt area 

WINDOWIISl 

"current" 

Window or Integer 0 

Current window on the screen, 0 if 




none 


"first" 

Window or Integer 0 

First window in VAXTPU's internal list 
of windows, 0 if none^ 


"last" 

Window or Integer 0 

Last window in VAXTPU's internal list 
of windows, 0 if none^ 


"next"2 

Window or Integer 0 

Next window in VAXTPU's internal 
list of windows, 0 if last^ 


"previous"^ 

Window or Integer 0 

Preceding window in VAXTPU's 
internal list of windows, 0 if first^ 

^Use string constants “current", or "first", 

before using "next". Use "current" or "last" before using 

"previous". 




3 An integer value of 1 indicates True and an integer value of 0 indicates False. 

^VAXTPU orders windows according to their "original top" line number. If multiple windows have the same 
top line number, the most recently created window comes first in VAXTPU's list of windows. 
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RETURN 

STATUS 

TPU$_BADREQUEST 

WARNING 

Request represented by second 

TPU$_BADKEY 

WARNING 

argument is not understood for data 
type of first argument. 

Bad keyword value or unrecognized 


TPU$_NOCURRENTBUF 

WARNING 

data type is passed as the first 
argument. 

Current buffer is not defined. 


TPU$_NOKEYMAP 

WARNING 

Key map is not defined. 


TPU$_NOKEYMAPLIST 

WARNING 

Key-map list is not defined. 


EXAMPLES 

D my.buffer :« GET.INFO (BUFFERS, "current"); 

This assignment statement stores the pointer to the current buffer in the 
variable my—buffer. 

2 my.etrlng :• GET.INFO (CURRENT.BUFFER, "file.name"); 

This assignment statement stores the name of the input file for the current 
buffer in the variable my—string. 

B i8.buf.mod GET.INFO ((nmRENT.BOFFER. "modified"); 

This assignment statement stores the integer 1 or 0 in the variable 
is—buf—mod. 1 means the current buffer has been modified. 0 means the 
current buffer has not been modified. 

Q my.window :■ GET.INFO (WINDOWS, "current"); 

length.integer GET.INFO (my.window, "vieible.length"); 
width.integer := GET.INFO (my.window, "width"); 

These assignment statements store the size of the current window in the 
variables length—integer and width—integer. 

g SAMPLE PROCEDURE 


The following procedure uses GET_INFO to find the top of the main window. 
It then removes the top five lines and replaces them with an example 
window. 

PROCEDURE uiwr.gatinfo 

top.of.window GET.INFO (main.window, "VISIBLE.TOP"); 

I Remove the top five lines from the main window 
ADJUST.WINDOW (main.window, +6, 0); 

! Replace removed lines with an example window 
axample.wlndow :• CREATE.WINDOW (top.of.window, 5, ON); 
example.buffer ;« CREATE.BUFFER ("EXAMPLE", 

"sysllogin:template.txt"); 

HAP (example.wlndow, example.buffer); 

ENDPROCEDURE; 
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^ SAMPLE PROCEDURE 


The following procedure retrieves and displays the name of the key-map list 
in the current buffer. 

current_k«y_nap_li«t :» GET.IHFO (CURRENT.BUFFER, "k«y_nnp.li»t"); 

MESSAGE (carrent_k«y_iMp_list); 


Q SAMPLE PROCEDURE 

The following procedure displays all the key-map lists. 

PROCEDURE sbow_key_nap_ll8t8 
LOCAL k8y_map_li8t_naae; 

key_map_li8t_nam« :« GET.IHFO (KEY_MAP_LIST, "firat"); 
LOOP 

EAITIF key.aap.list.name • 0; 

SPLIT_LINE: 

COPY.TEXT (key_]iiap_li8t_naiie); 

key_nap_li8t_najie GET.IHFO (KEy.MAP.LIST. "next"); 
EHDLOOP; 

EHDPROCEDURE; 


SAMPLE PROCEDURE 

The following procedure shows whether the key-map list associated with the 
current buffer inserts undefined printable characters. 

PROCEDURE show.sell.lnsert 
LOCAL key.map.list.name; 

key.nap.li8t.naae GET.IHFO (CURREHT.BUFFER, "key_nap.li8t"); 

IF GET.IHFO (key_aap_llBt_naae, "self.lnaert") 

THEM 

MESSAGE ("Undefined printable characters will be Inserted"); 

ELSE 

MESSAGE ("Undefined printable characters will cause an error"); 
EMDIF; 

EHDPROCEDURE: 


^ SAMPLE PROCEDURE 


The following procedure displays the key maps in the key-map list, key-map- 
list-name. 

PROCEDURE show_key_maps_ln_list (key.Bap_li8t.naBe) 

LOCAL key_Bap_naBe: 

key.Bap.naBe :> GET.IHFO (KEY_MAP, "first", key.Bap.list.naBe); 

LOOP 

EXITIF key_Bap_aaBe • 0; 

SPLIT.LIHE: 

COPY.TEXT (key_Bap_naBe); 

key.Bap_naBe ;» GET.IHFO (KEY.MAP, "next”, key_Bap_list_naBe); 

EHDLOOP; 

EHDPROCEDURE; 
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HELP_TEXT 


Invokes the VAX/VMS HELP utility. You must specify the help 
library to be used for help information, the initial library topic, the 
prompting mode for the HELP utility, and the buffer to which the 
help information is to be written. 


FORMAT HELP-TEXT (string 1, string2, keyword, buffer) 



parameters string 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the file specification of the 
help library. 

string2 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the initial library topic. If this 
string is empty, the top level of HELP is displayed. 

keyword 

The ke 3 rword that sets the prompting mode for the HELP utility. The valid 
keywords are ON and OFF: 

• ON—Specifies that the HELP utility should prompt the user for input. 

• OFF—Specifies that the prompting mode of the HELP utility should be 
turned off. 

buffer 

The buffer to which the help information is written. 


DESCRIPTION You can enter a complete file specification for the help library as the first 

parameter. However, if you enter only a file name, the HELP utility provides 
a default device (SYSSHELP:) and default file type (.HLB). 

If you do not specify an initial topic as the second parameter, you must enter 
a null string as a placeholder. The HELP utility then displays the top level of 
help available in the specified library. 

When prompting mode is ON for the built-in procedure HELP-TEXT 
procedure, the following prompt appears if the help text contains more 
than one window of information: 

Press RETURN to continue ... 

Prior to invoking the HELP utility, VAXTPU erases the buffer specified as 
the help buffer. (In EVE, and in the EOT Keypad Emulator, the buffer to 
which the help information is written is represented by the variable name 
HELP—BUFFER.) If the help buffer is associated with a window that is mapped 
to the screen, the window is updated each time VAXTPU prompts the user for 
input. If you turn the prompting mode OFF, then the window is not updated 
by the built-in procedure HELP-TEXT. 
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If HELP-BUFFER is not visible (associated with a window that is mapped to 
the screen), the information from the HELP utility is not visible. 

VAXTPU displays an error message if the help library specified by stringl is 
not found. If stringl is not found, a fatal error occurs. 


EXAMPLES 

□ HELP.TEXT Ctpuh^lp'. ", OFF .h«lp_buffer) 

This command causes the top level of help information from the 
SYS$HELP:tpuhelp.HLB library to be written to the help buffer. The HELP 
utility prompting mode is not turned on. 

S HELP.TEXT Ctpubelp', (READ.LINE {'Topic: ')), OFF. second.buller) 

This command prompts the user to provide the topic for the HELP utility. 
The information on that topic that is in the tpuhelp library is written to 
second-buffer. 

B SAMPLE PROCEDURE 

The following procedure displays information about getting out of HELP 
mode on the status line, prompts the user for input, and maps HELP—BUFFER 
to the screen. 

! + 

! Interactive HELP 
PROCEDURE user_help 

SET (STATUS.LINE. inlo_*indow. UNDERLINE, 

'Press CTRL/Z to leave proapts then CTRL/F to resume editing'}; 

MAP Cinlo.window, help.bulfer); 

HELP.TEXT CUSERHELP', READ.LINE ('TOPIC: '), ON, help.bulfer); 

ENDPROCEDURE 
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INDEX 

Locates a character or a substring within a string and returns its 
location within the string. 

FORMAT 

integer := 1 NDEX (string 1, string2) 

parameters 

string 1 

A string within which you want to find a character or a substring. 


string2 

A character or a substring whose leftmost character location you want to find 
within stringl. 

DESCRIPTION 

The built-in procedure INDEX finds the leftmost occurrence of string2 within 
stringl. It returns an integer that indicates the character position in stringl 
at which string2 was found. If stringl is not found, VAXTPU returns a zero. 
The character positions within stringl start at the left with 1. 

EXAMPLES 


Q loc := INDEX ('1234667','67') 

This assignment statement stores an integer value of 6 in the variable loc, 
because the substring '67' is found starting at character position 6 within the 
string '1234567'. 

Q SAMPLE PROCEDURE 


The following procedure uses the built-in procedure INDEX to return true if 
a given item is an alphanumeric character; otherwise, it returns false. (The 
list of characters in this example does not include characters from the DEC 
Multinational Character Set. However, you can write a procedure using those 
characters, because VAXTPU supports the DEC Multinational Character Set.) 
The parameter that is passed to this procedure is assumed to be a single 
character. 

PROCEDURE tt8«r_li_chairact«r (c) 

LOCAL symbol.cbaractars; 

sjnabol.charactars : • 

'<abcdelghl]klimopqrstuTwxyzABCDEFGBIJKLHN0PqRSTUVWXYZ1234ee7890''; 

IF INDEX (aynbol.charactera, c) > 0 
THEN RETURN 1; 

ELSE RETURN 0; 

ENDIF; 

ENDPROCEDURE 
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INT 

Converts a string that consists of numeric characters into an integer. 

FORMAT 

integer := INT (string) 

parameter 

string 

A string that consists of numeric characters. 

DESCRIPTION 

You can use this built-in procedure to store an integer value for a string of 
numeric characters in a variable. You can then use the variable name in 
operations that require integer data types. 

This built-in procedure returns 0 if the string is not a number. 

EXAMPLES 


□ user.int :■ INT ("12346") 

This assignment statement converts the string "12345" into an integer value 
and stores it in the variable user—int. 

2 SAMPLE PROCEDURE 


The following procedure is used by commands that prompt for integers. The 
procedure returns true if prompting worked or was not needed; it returns false 
otherwise. The number that is returned is returned in the output parameter. 


! Parameters: 

j 

! new.nuaber New integer value - output 

! prompt.atrlng Text of prompt - input 

! no_value_meaaage Meaaage printed if user presses the 

! RETURN key to get out of the command - input 

PROCEDURE user.prompt.number (nen.number, prompt.string, 

no_Talua_mas sage) 
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! String read alter prompt 
LOCAL read_llna_BtriDg; 

raad_line_8trlng :° READ_LINE (prompt.strlng); 

EDIT (read.llna_8tring, TRIM); 

IF read_lin8_8tring ■ 

THEN 

MESSAGE (no_Talue_ma88ags); 
naw_number :« 0; 

RETURN (0); 

ELSE 

TRANSLATE (read.line.8trlng. *1". "1"); 
ne«_number :> INT (r8ad_llne_Btrlng); 

IF (new.nomber ■ 0) and (read.llne.Btring <> "0”) 

THEN 

MESSAGE (FAO ("Don't understand !AS”, read_llne_strlng)); 
RETURN (0); 

ELSE 

RETURN (1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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JOURNAL. 

-CLOSE 


Closes an open journal file (if one exists for your session) and saves 
the journal file. 

FORMAT 

JOURNAL-CLOSE 

parameters 

None. 

DESCRIPTION 

Once you specify JOURNAL—CLOSE, VAXTPU does not keep a journal of 
your work until you specify JOURNAL—OPEN. Calling the built-in procedure 
JOURNAL—OPEN causes VAXTPU to open a new journal file for your 
session. 

RETURN 

STATUS 

TPU$_N0J0URNAL SUCCESS This VAXTPU session is not being 

journaled 

EXAMPLE 


JOURNAL.CLOSE 

This command causes VAXTPU to close the journal file, if one exists for your 
editing session. 
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JOURNAL_OPEN 


Opens a journal file and starts making a copy of your editing session 
by recording every keystroke and command that you execute. This 

procedure is not valid for batch mode. JOURNAI_OPEN optionally 

returns a string containing the file specification of the file journaled. 


FORMAT Estring2 :=1J0URNAL_0PEN (string 1) 


parameter string 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the name of the journal file 
created for your editing session. 


DESCRIPTION VAXTPU saves the keystrokes of your editing session in a buffer and writes 

the contents of this buffer to the fUe that you specify as a journal file. Recover 
your files with the same terminal characteristics with which your file was 
originally created. Otherwise, depending on how your interface is written, 
a journal file inconsistency may occur. JOURNAL—OPEN may return a 
SUCCESS message, but does not open a journal file when running without 
a terminal in batch mode (/NODISPLAY). It does not open a journal file for 
keystrokes in batch mode because there are no keystrokes in batch mode. 

See Section 6 for more information on recovering files with the qualifier 
/RECOVER. 

By default, keystrokes are written to the journal file whenever the buffer 
receives 500 bytes of new information. The default frequency for writing 
information to the journal file is the optimum frequency for high performance 
during your editing session. You can cause the journal buffer to be written to 
a file more frequently by specifying a lower value for the built-in procedure 
SET OOURNALING, integer). 
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RETURN 

STATUS 

TPU$_BADJOUCHAR 

WARNING 

VAXTPU expected to find a character 
in the journal file, but instead found 
something other than a character. 


TPU$_BADJ0UC0M 

WARNING 

You recovered your editing session 
with a different command file than 
you used during your original editing 
session. 


TPU$_BADJOUEDIT 

WARNING 

You recovered the editing session with 
an edit mode setting that was different 
from your original editing session. 


TPU$_BADJOUEIGHT 

WARNING 

You recovered the editing session 
with an eightbit setting that was 
different from that of your original 
editing session. 


TPU$_BADJOUFILE 

ERROR 

Inconsistency during recovery has 
terminated the recovery operation. 


TPU$_BADJOUINPUT 

WARNING 

You recovered the editing session with 
an input file that was different from 
the input file for your original editing 
session. 


TPU$_BADJOUKEY 

WARNING 

VAXTPU expected to find a key in the 
journal file, but instead found something 
other than a key. 


TPU$_BADJOULINE 

WARNING 

You recovered the editing session with 
a different line editing setting than you 
used for your original editing session. 


TPU$_BADJOUPAGE 

WARNING 

You recovered the editing session with 
a different page length than that used 
for your original editing session. 


TPU$_BADJOUSEC 

WARNING 

You recovered the editing session with 
a different section file than that used 
for your original editing session. 


TPU$_BADJ0USTR 

WARNING 

VAXTPU expected to find a string 
in the journal file, but instead found 
something other than a string. 


TPU$_CTRLCJOU 

WARNING 

A CTRL/C character was found in your 
journal file which may have made the 
rest of your journaling session invalid. 


TPU$_0PEN0UT 

ERROR 

The output file cannot be opened for 
output. 
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fS 


EXAMPLES 

□ J0URNAL_0PEN Ctest.fil’) 

This statement causes VAXTPU to open a file named test.fil as the journal 
file for your editing session. VAXTPU uses your current default device and 
directory to complete the file specification. 

Q SAMPLE PROCEDURE 

The following procedure starts journaling. It is called from the 
tpu$init_procedure after a file is read into the current buffer. 

PROCEDURE user.start.journal 
! Default journal name 
LOCAL default.joumal.nane, 

! Auxiliary journal ntune derived from file name 
aux_ j oumal_name; 

IF (GET.INFO (COMMAND.LINE. "journal") - 1) AND 
(OET.INFO (COMMAND_LINE, "road.only") <> 1) THEN 

aux_joumal_nane ;• GET.INFO (CURRENT.BUFFER, "flla.nama"); 

IF aux_joumal_naaa ■ THEN 

aux_joumal_name :■ GET.INFO (CURRENT.BUFFER, "output.file"); 

ENDIF; 

IF aux.joumal.name ■ 0 THEN 
aux.joumal.name :> ""; 

ENDIF: 

IF aux.joumal.naae « "" THEN 

default.joumal.name :> "user.TJL"; 

ELSE 

default.joumal.name :> ".TJL"; 

ENDIF; 

joumal.file GET.INFO (COMMAND.LINE. "joumal.file"); 
joumal.file :<• FILE.PARSE (joumal.file, default.joumal.name, 
aux_joumal_name); 

JOURNAL.OPEN (joumal.file); 

ENDIF; 

ENDPROCEDURE 
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KEY_NAME 


Returns a VAXTPU keyword for a key or a combination of keys. 


FORMAT keyword2 := 

key-name ] l,SHIFT_KEY]) 


parameters string 

A string that is the value of a key from the main keyboard. 

keyword 1 

A keyword that is the VAXTPU keyname for a key. 

SHIFT-KEY 

A parameter spedfying that the keyword that is returned is preceded by one 
or more shift keys. SHIFT-KEY refers to the VAXTPU shift key (PFl by 
default), not the SHIFT key on the keyboard. (See SET (SHIFT-KEY, ...).) 


DESCRIPTION KEY—NAME can be used with the built-in procedure DEFINE—KEY. When 

you want to bind executable code to a key or key combination for which a 
VAXTPU keyname does not exist, use KEY-NAME to create a keyword that 
VAXTPU accepts as a ke 5 mame. Table 3-5 lists the VAXTPU keynames for 
the VTIOO and VT200 series of keyboards. 

Single keyboard keys used with KEY—NAME are case sensitive, and the 
following statements generate two different ke)nvords: 

KEY.HAME CZ'); 

KEY.NAME Cz'); 

When you use the optional parameter SHIFT-KEY with the built-in procedure 
KEY—NAME, however, the keys are case insensitive and the following 
statements return the same keyword: 

KEY.NAME ('Z'. SHIFT.KEY); 

KEY_NAME ('z'. SHIFT.KEY); 


RETURN 

STATUS 


For a string: 
TPU$_MUSTBEONE 
For a keyword: 
TPU$_NOTDEFINABLE 


WARNING String must be one character long. 

WARNING Second argument is not a valid 
reference to a key. 
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EXAMPLES 

□ keyl KET.NAME CZ') 

This assignment statement creates the keyname keyl for the keyboard key Z. 

B keys KEY.NAME (KPS. SHIFT.KEY) 

This example uses KEY-NAME to create a keyname for a combination of 
keys. 

E keys KEY.NAME (ASCII (10)) 

This assignment statement creates the keyname key3 for the line feed control 
character. 

Q SAMPLE PKOCEDURE 


The following example shows a portion of a procedure that defines the keys 
for an editing interface that emulates EDT. 

I 

! Procedure to define keys to emulate EDT 
! 

PROCEDURE user.define.edtkey 

IBind the EDT find next function to PF3 
DEFINE_KEY (■edtSeearch.next■. PF3); 

!Bind the EDT find function to SHIFT PF3 
DEFINE_KEY ('edtlsearch', KEY.NAME (PF3, SHIFT.KEY)): 

ENDPROCEDURE 
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LAST_KEY 

Returns a VAXTPU keyword for the last key you entered. If you are 
replaying a learn sequence, it returns a keyword for the last key you 
replayed. 

FORMAT 

keyword := LAST_KEY 

parameters 

None. 

DESCRIPTION 

When replaying a learn sequence, LAST-KEY returns the last key replayed so 
far in the learn sequence, not the last key that was typed to invoke the learn 
sequence. 

When you invoke VAXTPU with the /NODISPLAY qualifier, the value zero 
is returned for LAST_KEY, except in the following case. If you precede the 
LAST—KEY statement with a READ—LINE statement, LAST—KEY can return 
a keyname representing the last key read by READ—LINE, CTRL/Z, or the 
RETURN key. See the description of READ—LINE for more information on 
the values that LAST—KEY can return when used while running VAXTPU in 
no display mode. 

EXAMPLES 


Q keyz := last.key 

This assignment statement stores the keyword for the last key you typed in 
the variable name keyz. 

Q SAMPLE PROCEDURE 

The following procedure prompts the user for input for key definitions. 

PROCEDURE U8er_defln«_kay 

del :• READ_LINE ('Definition: ■); 

key ;• READ.LINE ('Press key to define.',1); 

IF LENGTH (key) > 0 

THEN key :• KEY.NAME (key) 

ELSE key :• UST.KEY; 

ENDIF; 

DEFINE_KEy (del, key); 

ENDPROCEDURE 
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LEARN-BEGIN and LEARN_END 

Save ail keystrokes typed between LEARN-BEGIN and 
LEARN—END. LEARN-BEGIN starts saving all keystrokes that you 
type. LEARN-END stops the “learn mode" of VAXTPU and returns 
a learn sequence that consists of all the keystrokes that you entered. 


FORMAT LEARN-BEGIN (keyword) 


learn := LEARN_END 


parameter keyword 

Specifies the input for any READ—LINE, READ—KEY, or READ—CHAR built- 
in procedures that are a part of the learn sequence. The following are the 
valid keywords; 

• EXACT—Causes VAXTPU to use the input that was entered for each 
READ—LINE, READ—KEY, or READ—CHAR built-in procedures when the 
learn sequence was created as the input for these built-in procedures when 
the learn sequence is replayed. 

• NO—EXACT—Causes VAXTPU to prompt for new input each time a 
READ—LINE, READ—KEY, or READ—CHAR built-in procedure is replayed 
within a learn sequence. 


DESCRIPTION You can use the variable name that you assign to a learn sequence as the 

parameter for the built-in procedure EXECUTE to replay a learn sequence. 
You can also use the variable name with the built-in procedure DEFINE—KEY 
to bind the sequence to a key so that the learn sequence is executed when 
you press a key. 

Learn sequences are different from other VAXTPU programs in that they are 
created with keystrokes rather than with VAXTPU statements. You create the 
learn sequence as you are entering text and executing VAXTPU commands. 
Because learn sequences make it easy to collect and execute a sequence of 
VAXTPU commands, they are convenient for creating temporary "programs." 
You can replay these learn sequences during the editing session in wWch you 
create them. 

Learn sequences, created by collecting keystrokes, are not flexible enough to 
use for writing general programs. Learn sequences are best suited to saving a 
series of editing actions that you perform many times during a single editing 
session. 

It is possible to save learn sequences from session to session so that you can 
replay them in an editing session other than the one in which you created 
them. To save a learn sequence, bind it to a key and before ending your 
editing session, use the buUt-in procedure SAVE to do an incremental save 
to the section file you are using. Using the built-in procedure SAVE causes 
the new definitions from the current session to be added to the section file 
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with which you invoked VAXTPU. For more information, see the built-in 
procedure SAVE. 

Because there may possibly be changes to the VAXTPU key definitions in 
subsequent versions, you should be aware that you may lose learn sequences 
that you have saved when you run a new version of VAXTPU. 


Note: You should not use built-in procedures that can return WARNING or 
ERROR messages as a part of a learn sequence because learn sequences 
do not stop on error conditions. Because the learn sequence continues 
executing after an error or warning condition, the editing actions that are 
executed after an error or a warning may not take effect at the character 
position you desire. 


If, for example, a built-in procedure SEARCH that you use as a part of a 
learn sequence fails to find the string you specify and issues a warning 
condition, the learn sequence does not stop executing. This fact can cause 
the rest of the learn sequence to take inappropriate editing actions. 


RETURN 

STATUS 


TPU$_NOTLEARNING 

TPU$_ONELEARN 


WARNING 

WARNING 


LEARN—BEGIN was not used since last 
call to LEARN_END. 

A learn sequence is already in progress. 


EXAMPLE 


The following example shows how to combine LEARN—BEGIN and 
LEARN—END so that all of the keystrokes that you enter between them 
are saved. The keyword (EXACT) specifies that, if you use READ—LINE, 
READ—CHAR, or READ—KEY withht the learn sequence, any input that you 
enter for these built-in procedures is repeated exactly, when you replay the 
learn sequence. 

LEAHN_BEGIN (EXACT) 


This would be a tjrplcal editing session, 
in which you perloro coonands that are 
bound to keys. 


do.agaln :• LEAKN.END 
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LENGTH 

Returns an integer that is the number of character positions in a 
string or a range. 

FORMAT 

integer := LENGTH 

1 range J 

parameters 

string 

The string whose length you want to determine. 


range 

The range whose length you want to determine. If you specify a range, line 
terminators are not counted as character positions. 


EXAMPLES 

D str.len LENGTH ('Don Quixote') 


This assignment statement stores the number of characters in the string ‘Don 
Quixote’ in the variable str—len. In this example, the integer value is 11. 

Q u8er_how_long :• LENGTH (ay.range) 

This assignment statement stores the number of character positions (excluding 
line terminators) in my—range in the variable user—how—long. 

S SAMPLE PROCEDURE 


The following procedure puts a marker without any video attributes at 
the current position. The marker is assigned to a variable that begins 
with user_mark_ and ends with the string you pass as a parameter. The 
procedure writes a message to the message area verifying the mark_name 
that comes from the input parameter. 

I 

! Parametsrs: 

! 

I iMrk_parwMt«r String to uie as a mark name ■ Input 

PROCEDURE UBer_mark (mark_parametar) 

! Local copy of mark_parameter 

LOCAL mark_name; 

0N_ERR0R 

MESSAGE (FAO ("Cannot use !AS as a mark name", mark_name)); 

RETURN: 

ENDON_ERROR; 
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! 132 - length Cuser.aark.') 

IF LENGTH (mark.parameter) > 122 
THEN 

mark.name :> SUBSTR (mark_nBiae, 1, 122); 

ELSE 

mark.nam* :» iiark_parnm«t«r; 

ENDIF; 

EXECUTE ("u«er_mark." ♦ mark_n«jn« ♦ » :- MARK (NONE)"); 
MESSAGE (FAQ ("Current poeitlon marked at IAS", mark_aame)); 
ENOPROCEDURE 



VAXTPU Built-In Procedures 

LINE-BEGIN 


LINE_BEGIIM 


Returns a pattern that matches the beginning-of-line condition. 


FORMAT pattern := LINE_BEGiN 


parameters None. 


DESCRIPTION LINE_BEGIN is one of the VAXTPU built-in procedures that allows you to 

search for complex strings by creating patterns that match certain conditions. 
For example, if you want to find all occurrences of the exclamation mark 
(!) when it is the first character in the line, use the built-in procedure 
LINE—BEGIN to create the following pattern: 

patl :• LINE_BEGIN t ■!'; 

When used with the built-in procedure SEARCH, patterns that use 
LINE—BEGIN do not move the current character position to the beginning of 
a line when a match is found for the beginning of line condition. You must 
use the built-in procedure POSITION to move the current character position 
to the beginning of a range that matches a pattern. 

For more information on patterns, see Section 2. 


EXAMPLES 

Q patl :> LINE.BEGIN 

This assignment statement stores the beginning of line condition in the 
variable patl. 

Q SAMPLE PROCEDURE 


This procedure removes all runoff commands from a file by searching for a 
pattern that has a dot (.) at the beginning of a line and then removing the 
lines that match this condition. 

PROCEDURE uaer.remoTe.dsrlines 
LOCAL al, patl; 

patl ;• LINE_BEGIN A 
LOOP 

al ;• SEARCH (patl, FORWARD); 

EXITIF al - 0; 

POSITION (al); 

ERASE_LINE; 

EHDLOOP 

ENDPROCEDURE 
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LINE_END 

Returns a pattern that matches the end-of-line condition. 

FORMAT 

pattern := LINE_END 

parameters 

None. 

DESCRIPTION 

The end-of-line condition is one character position to the right of the last 
character on a line. 

When used with the built-in procedure SEARCH, LINE-END does not move 
the current character position to the beginning of the next line when a match 
is found for the end-of-line condition. You must use the buUt-in procedure 
POSITION to move the current character position to the beginning of a range 
that matches a pattern. 

For more information on patterns, see Section 2. 


EXAMPLES 

Q patl :> LINE.END 


This assignment statement stores the end-of-line condition in the variable 
name patl. 

Q SAMPLE PROCEDURE 


If you are not already at the end of the current line, the following procedure 
moves the current character position to the end of the line. 

PROCEDURE user_end_or_llne 

eol.pattern :■ LINE_END; 

eol.range :■ SEARCH (eol.pattarn, FORWARD); 

IF eol.ranga <> 0 

THEN POSITION (eol.range); 

ENDIF; 

ENDPROCEDURE 
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LOOKUP-KEY 


Returns the executable code or the comment that is associated with 
the key you specify. The code can be returned as a program or as a 
learn sequence. The comment is returned as a string. 


FORMAT 


program 

learn 

* m . * 

integer 
. string2 

LOOKUP-KEY (keywords keyword2string 1]l) 


parameters keyword 1 

A VAXTPU keyname for a key or a combination of keys. See Table 3-5 for a 
list of the VAXTPU keynames for the VTIOO and VT200 series of keyboards. 

keyword2 

A keyword that specifies the item that is associated with the key you 
are looking up. The valid keywords are PROGRAM, COMMENT, and 
KEY-MAP. 

• PROGRAM—Specifies that either a program or a learn sequence is 
returned if the key was defined. If the key was not defined, VAXTPU 
returns the integer zero. 

• COMMENT—Specifies that the comment string that was given when the 
key was defined with DEFINE—KEY, is returned. If no comment was 
given, a null string is returned. 

• KEY—MAP—Specifies that the string given for the key map when the key 
was defined with DEFINE—KEY is returned. 

String 1 

An optional string that causes the procedure to return the requested 
information from the specified key map, or from the first definition for 
the key in the specified key-map list. If neither a key map nor a key-map list 
is specified, the first definition in the key-map list bound to the current buffer 
is returned. 


DESCRIPTION This built-in procedure can return a program, a learn sequence, a string, or 

the integer zero (zero means that the key has no definition). 

LOOKUP—KEY is useful when you are doing temporary key definitions during 
an editing session and you want to check existing definitions of keys. 
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RETURN 

STATUS 


TPU$_NOTDEFINABLE 

WARNING 

TPU$_NOKEYMAP 

WARNING 

TPU$_NOKEYMAPLIST 

WARNING 

TPU$_KEYMAPNTFND 

WARNING 

TPU$_EMPTYKMLIST 

WARNING 


Second argument is not a valid 
reference to a key. 

Third argument is not a defined key 
map. 

Third argument is not a defined 
key-map list. 

The key map listed in the third 
argument is not found. 

The key-map list specified in the third 
argument contains no key maps. 


EXAMPLES 

□ programx :> LOOKUP.KEY (keyl, PROGRAM) 


Q SAMPLE PROCEDURE 


This assignment statement returns the executable code that is associated with 
keyl. The second keyword PROGRAM indicates that the result is returned in 
a program or a learn data type. 


The following procedure displays in the message area the comment that 
included with your key definition for the last key that you typed. 


you 



PROCEDURE user.what.is.commant 

MESSAGE (L00KUP_KEY (LAST.KEY, COMMENT)); 

ENDPROCEDURE 


g] SAMPLE PROCEDURE 


The following procedure returns the comment string associated with a 
particular key. 


PROCEDURE UBer_g«t_key_liilo 
LOCAL key.to.intarprat, kay.inlo; 


MESSAGE (’Press the key you want information on: ”); 
key.to.lnterpret :• READ.KEY; 

kay.lnfo := LOOKUP.KEY (key.to.lnterpret, COMMENT); 

IF key.info <> •” 

THEN MESSAGE ("Comment: " * key.inlo); 

ELSE MESSAGE ("No comment is associated with that key."); 
ENDIF; 

ENDPROCEDURE 


Q SAMPLE PROCEDURE 


The following procedure returns the key map within the key-map list, 
TPU$KEY_MAP_UST, in which the RETURN key is defined. 

key_map_name LOOKUP.KEY (RET.KEY, KEY_MAP. "tpu*key.map.list"); 

IF LENGTH (key.nap.naBe) • 0 
THEN 

MESSAGE ("RET.KEY is undefined"); 

ELSE 

MESSAGE ("RET.KEY is defined in key map " + key.map.name); 

ENDIF; 
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g SAMPLE PROCEDURE 


The following procedure implements multiple "shift" keys 

PROCEDURE 8hllt_key_handlar (kay_map_list_iiain); 

LOCAL bound.program; 

bound.prograin ;> LOOKUP.KEY (READ.KEY, PROGRAM, ■key.aap.llst.nuie”); 

IF bound_prograD <> 0 
THEN 

EXECUTE (bound_progra]ii); 

ELSE 

MESSAGE ("Attempt to execute undefined key"); 

ENDIF; 

ENDPROCEDURE; ! ehlft.key.handler; 
red_keys CREATE.KEY.MAP ("red.keyi"); 

red_key_nap_liBt :» CREATE_KEY_MAP_LIST ("red_key_map_li8t". red.keye); 

DEFINE_KEY ("8hilt_key_handler (red_key_nap_liBt)", PF3, "RED Bhift key"); 
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MAP 

Associates a buffer with a window and causes the window to 
become visible on the screen. Before using MAP you must already 
have created the buffer and the window that you specify as 
parameters. See CREATE-BUFFER and CREATE_WINDOW. 

FORMAT 

MAP (window, buffer) 

parameters 

window 

The window you want to map to the screen. 


buffer 

The buffer you want to associate with the window. 

DESCRIPTION 

The window and buffer that you use as parameters become the new current 
window and the new current buffer, respectively. The cursor position on the 
screen is the same as the current character position in the buffer. 


MAP may cause other windows that are mapped to the screen to be partially 
or completely occluded. If MAP causes the new window to segment another 
window into two pieces, only the upper part of the segmented window 
remains visible and continue to be updated. The lower part of the segmented 
window is erased on the next screen update. If you remove the window that 
is segmenting another window, VAXTPU totally repaints the screen so that 
the window that was segmented assumes its original size and position on the 
screen. 


Note that if you execute MAP within a procedure, the screen is not updated 
to reflect the new mapping until the procedure has finished executing and 
control has returned to the screen manager. Items such as repainting of 
windows and erasure of lines does not occur until control is returned to the 
screen manager. If you want the screen to reflect the changes before the 
entire program is executed, you can force the immediate update of a window 
by adding an UPDATE statement to the procedure. 

RETURN 

STATUS 

TPU$—MAXMAPPEDBUF WARNING Buffer is mapped to its window limit. 


EXAMPLES 

Q MAP (maln.window, maln.bulfer) 


This command associates the main buffer with main window and maps the 
main window to the screen. You must have established the main buffer and 
the main window with CREATE—BUFFER and CREATE—WINDOW before 
you can use them as parameters for MAP. 
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Q SAMPLE PROCEDURE 


The following procedure creates a message buffer and a message window. It 
then associates the message buffer with the message window and maps the 
message window to the screen. 

PROCEDURE u«ar_mes8ag*_window 

nassaga.batlar :• CREATE_BUFFER Caattag*”); 

SET (EOB.TEXT, aaiaaga.butfar, ■>*); 

SET (NO.WRITE, aataaga.bullar); 

SET (SYSTEM, aaaaaga.bullar); 
aasaaga.windoir :> CREATE.WINDOW (23, 2, OFF); 

SET (VIDEO, aasaaga.wlndow, NONE); 

MAP (aasaaga.wlndow, aassage.buffar); 

ENDPROCEDURE 
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MARK 


Returns a marker for the current character position in the current 
buffer. You must specify how the marker is to be displayed on 
the screen (no special video, reverse video, bolded, blinking, or 
underlined). 


FORMAT marker := MARK (keyword) 

parameter keyword 

You must use one of the following keywords: 

• NONE—Applies no video attributes to marker. 

• BOLD—Causes the marker to be bolded. 

• BLINK—Causes the marker to blink. 

• REVERSE—Causes the marker to be displayed in reverse video. 

• UNDERLINE—Causes the marker to be underlined. 


DESCRIPTION This built-in procedure can be used to establish placeholders, or "bookmarks." 

The marker is tied to the character that indicates the current character position 
when the built-in procedure MARK is executed. If the character tied to the 
marker moves, the marker moves also. If the character tied to the marker 
is deleted, the marker moves to the nearest character position. The nearest 
character position is determined in the following way: 

1 If there is a character position on the same line to the right, the marker 
moves to this position, even if the position is at the end of the line. 

2 If the line on which the marker is located is deleted, the marker moves to 
the first position on the following line. 

You can move one column past the last character in a line and place a marker 
there. However, you cannot see a video attribute for the marker unless the 
marker is moved to another screen location. 

If you use a marker at the end of a line as a part of a range, even though the 
marker is not positioned on a character, it is included in the range. 


EXAMPLES 

Q user.mark MARK (NONE) 

This assignment statement places a marker at the current character position. 
There are no video attributes applied to the marker. 

Q user.mark.under := MARK (UNDERLINE) 
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marker is underlined. 
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S my_Dark :> MARK (UNDERLINE): ny_aark HARK (BLINK) 

This assignment statement places a marker at the row and column position 
that corresponds to the current character position. The character tied to the 
marker is underlined and blinks. 

Q SAMPLE PROCEDURE 


The following procedure marks a temporary position at the current character 
position, and then goes to the paste buffer and creates a range of the contents 
of the paste buffer. VAXTPU then goes to temp_pos and copies the text from 
the paste buffer at the temporary position. 

PROCEDURE usar.paste 

teap_pos :> MARK (NONE); 

POSITION (END.OF (paste.bulfer)); 

M0VE_H0RIZ0NTAL (-2); 

paste.text :• CREATE.RANGE (BEGINNING.OF (paate.bullar), 

HARK (NONE), NONE); 

POSITION (taBp_po8); 

COPT.TEIT (paste.text): 

ENDPROCEDURE 
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MATCH 

Returns a pattern that matches a sequence of characters starting at 
the current character position and continuing up to and including all 
the characters specified in the parameter string. 

FORMAT 

pattern := MATCH (string) 

parameter 

string 


A quoted string, or a variable name representing a string constant that 
contains the characters that you want to be the final part of the pattern. 

DESCRIPTION 

For a string to match a pattern that is returned by the built-in procedure 
MATCH, it must contain all of the characters that you specify as a parameter. 
The pattern that MATCH returns does not cross record (line) boundaries. 


EXAMPLES 

□ patl ;> HATCH ('abc>) 


This assignment statement stores in patl a pattern that matches a string of 
characters starting with the current character position up to and including the 
characters "abc*. 


Q SAMPLE PROCEDURE 


The following procedure finds text within double parentheses. It moves the 
current character position to the beginning of the parenthetical text, if it exists. 

PROCEDURE ttsar.doubla.parana 

paran_text ;« •((• t MATCH ('))*); 

lottnd_ranga :« SEARCH (paren_text. FORWARD, NONEXACT); 

IF found_range >0 ! No match 

THEN MESSAGE ('No match found.'); 

ELSE POSITION (found.ranga); 

ENDIF 

ENDPROCEDURE 
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MESSAGE 

Inserts the characters in the string or range that you specify into 
the message buffer, if one exists (by default, VAXTPU looks for 
a buffer variable that is named MESSAGE-BUFFER). If there is no 
MESSAGE-BUFFER, VAXTPU displays the message at the current 
location on the device pointed to by SYS$OUTPUT (usually your 
terminal). 


FORMAT 

MESSAGE (1 b 

[ range J 


parameters 

string 

Either a quoted string or a variable representing the text you want to include 
in the message buffer. 



range 

The range that contains the text that you want to include in the message 
buffer. 


DESCRIPTION 

The purpose of the built-in procedure is to provide the user who is writing 
an eating interface with a method of displaying messages in a way that is 
consistent with the VAXTPU language. If you have associated a message 
buffer with a message window, and if the message window is mapped to the 
screen, the string or range you specify appears immediately in the message 
window on the screen. 



If you have not associated a message buffer with a message window, 
messages are written to the buffer, but do not appear on the screen. 


EXAMPLES 

D MESSAGE ('Hallo') 


This command writes the text 'Hello' in the message area. 
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Q SAMPLE PROCEDURE 


The following procedure determines whether the cursor is at the end of the 
line. It sends a text message to the message area on the screen about the 
position of the cursor. 

PROCEDURE uiar.on.eol 
i test 11 St eol, return true or false 
M0VE_B0RIZ0NTAL (1); 

IF CURRENT.OFFSET « 0 !then we are on eol 
THEN 

user_on_end_ol_line :• 1; !return true 

MESSAGE ("Cursor at end of line”); 

ELSE 

user_on_end_of_llne :• 0: tretum falsa 

MESSAGE ("Cursor is not at the end of lins"); 

ENDIF; 

M0VE_H0RIZ0NTAL (-1); Inove back 
ENDPROCEDURE 
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MOVE_HORIZONTAL 


Changes the current character position in the current buffer by the 
number of characters you specify. 


FORMAT MOVE_HORIZONTAL (integer) 


parameter integer 

The signed (+/“) integer value that indicates the number of characters 
the current character position should be moved. A positive integer causes 
movement toward the end of the buffer. A negative integer causes movement 
toward the beginning of the buffer. 


DESCRIPTION The horizontal adjustment of the character position is tied to text. 

MOVE—HORIZONTAL crosses line boundaries to adjust the current character 
position. 

The character position adjustment caused by MOVE—HORIZONTAL is not 
visible on the screen unless the cursor position and the current character 
position are the same (the current buffer must be associated with a window 
that is ciurently mapped to the screen). If they are the same, VAXTPU causes 
the screen to scroll (if necessary) so that the character position you establish 
with MOVE—HORIZONTAL is within the scrolling limits set for the window 
that is associated with this buffer. 

If you try to move past the beginning or the end of a buffer, VAXTPU 
displays a warning message. 


RETURN 

STATUS 


TPU$_NOCURRENTBUF 

TPU$-ENDOFBUF 

TPU$-BEGOFBUF 


WARNING You are not positioned in a buffer. 

WARNING You are trying to move forward past 
last character of buffer. 

WARNING You are trying to move in reverse past 
first character of buffer. 


EXAMPLES 

□ H0VE_H0RIZ0NTAL (+5) 


This command moves the current character position five characters to the 
right in the current buffer. 
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S SAMPLE PROCEDURE 


The following procedure moves text by sections that are eight lines long, 
and uses MOVE—HORIZONTAL to put the current character position at the 
beginning of the line. 

PROCEDURE ut«r_Dov«_by_llM* 

IF CURRENT.DIRECTION - FORWARD 
THEN 

MOVE_VERTICAL (8) 

ELSE 

MOVE_VERTICAL(- 8) 

ENDIF; 

M0VE_H0RIZ0NTAL (-CURRENT.OFFSET); 

ENDPROCEDURE 
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MOVE_TEXT 


Moves the text you specify and places it in front of the current 
character position in the current buffer. When you move text with 
range and buffer parameters, you remove it from its original location. 


FORMAT r string ] 

MOVE_TEXT (\ range ]) 

[ buffer ) 


parameters string 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that represents the text that you want to 
move. Text is not removed from its original location with this argument. 

range 

The range that contains the text you want to move. 

buffer 

The buffer that contains the text you want to move. 


DESCRIPTION If the current buffer is in insert mode, the text you specify is inserted before 

the current position in the current buffer. If the current buffer is in overstrike 
mode, the text you specify replaces text starting at the current position and 
continuing for Ae length of the string, range, or buffer. 

Markers and ranges are not moved with the text. If the text of a marker or 
a range is moved, the marker or range structure and any video attribute that 
you specified for the marker or range are moved to the next closest character. 
The next closest character is always a character following the marker or range. 
To remove the marker or range structure use the built-in procedure DELETE 
or set the variable to which the range is assigned to zero. 

MOVE-TEXT is similar to COPY-TEXT. However, MOVE-TEXT erases the 
text from its original location, while COPY—TEXT just makes a copy of the 
text for the new location. 

Note: You cannot add a buffer or a range to itself. If you try to add a buffer 
to itself, VAXTPU issues an error message. However, VAXTPU does 
not check for this condition for a range. If you are positioned within 
the range represented by the variable my—range, a statement like the 
following may cause an infinite loop: 

H0VE_TEXT (By_raiig«} 

Press CTRL/C to stop the loop. 
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RETURN 

STATUS ^ 

TPU$_NOCACHE ERROR There is not enough memory to allocate 

a new cache. 


EXAMPLES 

D H0VE_TEXT (iialn_bulfer) 

If you are using insert mode for text entry, this command causes the text from 
main-buffer to be placed in front of the current position in the current buffer. 
The text is removed from main-buffer. 


Q SAMPLE PROCEDURE 


The following procedure puts the text from the scratch buffer in front of the 
current character position in the main buffer. The text in the scratch buffer is 
removed; no copy of it is left there, 

PROCEDURE U8er_moTe_text 
LOCAL thl8_mode; 

! Save node ol current bulfer in thie.mode 

thi8_mode GET.IKFO (CURRENT_BUFFER. "mode"); 

! Set current buffer to inaert mode 
SET (INSERT. CURRENT.BUTFER); 

! Move the scratch buffer text to the current buffer 
M0VE_TEXT (8cratch_bnffer): 

! Reset current buffer to original mode 
SET (thi8_node. CURRENT_BUFFER); 

ENDPROCEDURE 
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MOVE_VERTICAL 


Modifies the current character position in the current buffer by the 
number of lines you specify. 


FORMAT MOVE-VERTICAL (integer) 


parameter integer 

The signed (+/“) integer value that indicates the number of rows that the 
current position should be moved. A positive integer causes movement 
toward the end of the buffer. A negative integer causes movement toward 
the beginning of the buffer. 


DESCRIPTION The adjustment that MOVE-VERTICAL makes is tied to text. VAXTPU 

tries to retain the same character offset relative to the beginning of the line 
when moving vertically. However, if there are tabs in the lines, the character 
position probably does not retain the same column position on the screen. 

The character position adjustment caused by MOVE—VERTICAL is not visible 
on the screen unless the cursor position and the current character position 
are the same (the current buffer must be associated with a window that is 
currently mapped to the screen). If they are the same, VAXTPU causes the 
screen to scroll (if necessary) so that the character position that you establish 
with MOVE-VERTICAL is visible. 

If you try to move past the beginning or end of a buffer, VAXTPU displays a 
warning message. 


RETURN 

STATUS 


TPU$_BEGOFBUF 

TPU$_ENDOFBUF 

TPU$_NOCURRENTBUF 


WARNING 

WARNING 

WARNING 


You are trying to move forward past 
first character of buffer. 

You are trying to move in reverse past 
last character of buffer. 

You are not positioned in a buffer. 


EXAMPLES 

□ MOVE_VERTICAL (+5) 


This command moves the current position in the current buffer vertically 5 
rows toward the end of the buffer. 
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Q SAMPLE PROCEDURE 


The following procedure moves text by sections that are eight lines long. 

PROCEDURE usar_DOve.8_llnaa 

IF CURRENT_DIRECTION • FORWARD 
THEN 

MOVE_VERTICAL (8) 

ELSE 

MOVE.VERTICAL (- 8) 

ENDIF; 

M0VE_H0RIZ0NTAL(- CURRENT.OFFSET); 

ENDPROCEDURE 
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NOTANY 

Returns a pattern that matches any single character not in the string 
that is used as a parameter. 

FORMAT 

pattern := NOTANY (string) 

parameter 

string 

A quoted string, or a variable name representing a string constant that 
contains characters that cause a match of the pattern to fail. 

DESCRIPTION 

When used with the built-in procedure SEARCH, the pattern returned by 
NOTANY causes a successful match if none of the characters in the pattern is 
found in the text being searched for a match. 

The pattern returned by NOTANY matches a single character. This behavior 
is different from the built-in procedure SCAN that returns a pattern that 
matches the longest string of characters that does not contain any of the 
characters in a specified string. See SCAN and SCANL for more information. 

For more information on patterns, see Section 2. 


EXAMPLES 

□ patl :* NOTANY ('XYZ') 


This assignment statement creates a pattern that matches the first character 
that is not an X, a Y, or a Z. The match fails if a character (other than X, Y, or 
Z) is not found. 

Q SAMPLE PROCEDURE 



The following procedure starts at the current location and looks for the first 
non-alphabetic, non-lowercase character. The variable non—alpha—range 
stores the character that matches these conditions. 

PROCEDURE u8ar_a«arch_lor_nonalpha 

noii_alpha_patt«rn :• NOTANY ('abcdatghijklmnopqrttUTwxyz'): 
non.alpba_raiiga :• SEARCH (iion_alpha_patters, FORWARD, NO.EXACT); 

IF (noii_alpha_ra]>g8 • 0) 

THEN 

aser_8earch_for_fir8t_iionalpha ;• 0; 

ELSE 

n88r_88arcli_for_fir8t_noDalpba ;• BEGINNING.OF 

(noi>_alpha_range}; 

ENDIF; 

ENDPROCEDURE 

! 

! The value of this procedure la either a marker pointing 
! to the next non-alphabetlc character or the Integer zero 
! 11 no non-alphabetic chuacters are found. You can call 
I it In the following way; 

! non_alpba_marker :• U8er_8earch_for_nonalpha; 
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POSITION 


Establishes the current character position in the editing context. You 
can position to a range, a marker, a buffer, or a window. 


FORMAT 


POSITION f 


buffer 

marker 

range 

window 


} 


parameters buffer 

The buffer in which you want to place the current character position; it 
becomes the last position you occupied in the buffer. 

marker 

The marker to which you want to tie the current character position. 

range 

The range in which you want to place the current character position; it is at 
the beginning of the range. 

window 

The window in which you want to place the current character position. 

The window must be mapped to the screen. The current character position 
becomes the row and column on the screen that you occupied the last time 
you were positioned in this window. 


DESCRIPTION Positioning to a window causes the buffer associated with the window to 

become the current buffer. 

Positioning to a buffer, a range, or a marker does not necessarily move the 
cursor position. VAXTPU does not change the cursor position unless the 
cursor is in a window associated with the buffer that is specified or implied 
by the POSITION parameters. If you want to do visible editing, you should 
position to a window rather than a buffer. 

If you try to position to an invisible window, VAXTPU issues a warning 
message. 


RETURN 

STATUS 


TPU$_WINDNOTMAPPED WARNING Window is not mapped to the screen. 
TPU$_WINDNOTVIS WARNING Window is totally occluded. 
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EXAMPLES 

D POSITION (message.window) 

This command moves your current character position to the message window. 
Your position in the window is the same character position you occupied 
when you were last positioned in the window. 

Q U8ar_aark :• MARK(NONE): 

POSITION (a8«r_nark) 

These statements make the current character position the marker associated 
with the variable user—mark. 

g] SAMPLE PROCEDURE 


The following procedure moves the current character position between two 
windows. (Note that the current buffer is implicitly changed also.) 

PROCEDURE u8er_change_wliidow8 

IF CURRENT.WINDOW « Daln_«indow 
THEN POSITION (extr8.wlndow); 

ELSE POSITION (inalii_wlndow); 

ENDIF; 

ENDPROCEDURE 
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QUIT 

Leaves the editor without writing to a file. 

FORMAT 

QUIT 

parameters 

None. 

DESCRIPTION 

If you modify any buffers that are not SET (NO_WRITE, ... ) VAXTPU tells 
you that you have modified buffers and asks whether you want to quit. Enter 
Y (Yes) if you want to quit without writing out any modified buffers. Enter N 
(No) if you want to retain the modifications you have made and return to the 
editor. 


EXIT is the built-in procedure to use when you have made changes and want 
to save them when you leave the editor. (For more information, see the 
description of EXIT.) 


A special use of the built-in procedure QUIT is at the end of your section file 
when you are compiling it for the first time. See Section 5, VAXTPU Program 
Development, for information on creating section files. 

RETURN 

STATUS 

TPU$_CANCELQUIT WARNING 'NO' response was received from 

' . . . continue quitting?' prompt. 


EXAMPLES 

D QUIT 


This command returns the editor to the caller. If you have modified any 
buffers, you see the following prompt: 

Buffer modifications will not be saved, continue quitting (Y or N)? 

Enter Y(es) if you want to quit and not save the modifications. Enter N(o) if 
you want to return to the editor. 

The following example contains statements similar to those in the last part 
of the EDTSECINI.TPU file that creates the EDT Keypad Emulator. The 
SAVE statement creates a section file that is saved in binary format. The 
QUIT statement causes an exit from VAXTPU without any changes to the file 
EDTSECINI.TPU. 


POSITION (maln_window); 

tputlocal.lnlt: 

edt$deflne_ke 7 s; ! bind keys 

SAVE ('SYSILIBRARY;EDTSECINI.TPOlSECTION'); 

QUIT; 
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Q SAMPLE PROCEDURE 


The following procedure turns off the display of the success message, 'Editor 
successfully quitting", when you use the built-in procedure QUIT to leave an 
editing interface. 

PROCEDURE utar.qult 
SET (SUCCESS, OFF): 

QUIT: 

{Turn mesiag* back on in caaa user aniwers "No" to tha 
Ipronpt *Buriar aodlficatlona will not be eaved, continue 
!quitting (T or N)7* 

SET (SUCCESS, ON): 

ENDPROCEDURE 
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READ-CHAR 

Stores the next character entered from the keyboard in a string 
variable. 

FORMAT 

string := READ.CHAR 

parameters 

None. 

DESCRIPTION 

The character read by READ_CHAR is not echoed on the screen; therefore, 
the cursor position does not move. 

READ—CHAR does not process escape sequences. If a VAXTPU procedure 
uses READ—CHAR for an escape sequence, only part of the escape sequence 
is read. The remaining part of the escape sequence is treated as text 
characters. If control then returns to VAXTPU, or a READ—KEY or a 

READ—LINE is executed, the results may be unpredictable. 

EXAMPLES 



Q new.ehar :• REAO.CHAR 


This assignment statement stores the next character that is entered on the 
keyboard in the string new_char. 

Q SAMPLE PROCEDURE 


The following procedure enters the next character that is entered from the 
keyboard in the current buffer. If a key that sends an escape sequence is 
pressed, the entire escape sequence is added to the buffer, as if it were regular 
text. 


PROCEDURE utar.quote 
COPY.TEXT (READ.CHAR); 
ENDPROCEDURE 
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READ-FILE 


Reads a file and adds the contents of the file immediately before the 
current line in the current buffer. READ-FILE optionally returns a 
string containing the file specification of the file read. 


FORMAT |[string2:=lREAD_FILE (string 1} 



parameter string 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the name of the file you want 
to read and include in the current buffer. 


DESCRIPTION VAXTPU writes a message indicating how many records (lines) were read. 



RETURN 

STATUS 

TPU$_NOCURRENTBUF 

WARNING 

You are not positioned in a buffer. 

TPU$_CONTROLC 

ERROR 

The execution of the read terminated 
because you pressed CTRL/C. 



TPU$_NOCACHE 

ERROR 

There is not enough memory to allocate 
a new cache. 



EXAMPLES 

□ REAO_FILE ('logln.com') 

This Statement reads the file login.com and adds it to your current buffer. 

Q SAMPLE PROCEDURE 


The following procedure creates a second window and a second buffer and 
maps the window to the screen. The procedure also prompts the user for a 
file name to include in the buffer and defines the editor SHIFT-KEY (PFl by 
default) and W key combination as the key by which to move to the second 
window. 

PROCEDURE user.two.windows 

w2 ;• CREATE_WINDOW (1. 10, ON); 

b2 CREATE_BUFFER ('bul2'); 

MAP («2, b2): 

REAO_FILE (READ_LINE ('Enter file name lor 2nd window : ')); 

POSITION (BEGINNING.OF (b2)); 

DEFIKE_KEY ('POSITION (w2)', KEY.NAME ("W". SHIFT.KEY)); 

ENDPROCEDURE 
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READ-KEY 


Waits for you to press a key and then returns the keyword for that 
key. 

FORMAT 

keyword := READ-KEY 

parameters 

None. 

DESCRIPTION 

This built-in procedure should be used rather than READ—CHAR when you 
are entering escape sequences, control characters, or any characters other 
than text characters. READ—KEY processes escape sequences and VAXTPU's 
SHIFT-KEY (PFl by default). 

The key that is read by READ—KEY is not echoed on the terminal screen. 

EXAMPLES 

□ my.key READ.KEY 

Q SAMPLE PROCEDURE 

This assignment statement reads the next key that is entered and stores the 
keyword for that key in the variable my—key. 


The following procedure sets the SHIFT-KEY to the last (that is, current) key, 
reads in the next key, and returns the keyname for the shifted key. VAXTPU 
does not save the SHIFT-KEY setting from session to session. Use the 
built-in procedure DEFINE—KEY with the variable key—toshift that is 
returned if you want to save the SHIFT-KEY that you define from session to 
session. 

PROCEDURE U8er_get_shiltkey 

! Kayword lor key pressed alter shllt key 

LOCAL key_to_8bilt; 

SET (SHirT_KEY. LAST.KEY); 

key.to.shilt ;• KEY.NAME (READ.KEY, SHIFT.KEY); 

RETURM (key.to.shilt); 

ENDPROCEDURE 
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READ_LINE 


Displays the text that you specify as a prompt for input and reads 
the information entered in response to the prompt. You can 
optionally specify the maximum number of characters to be read. 
READ-LINE returns a string that holds the data that is entered in 
response to the prompt. 


FORMAT string2 := READ-LINE [(string 1 [Jnteger] 


parameters string 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the text used as a prompt for 
input. This parameter is optional. 

integer 

The integer value that indicates how many characters to read from the input 
entered in response to the prompt. The maximum number is 132 which 
corresponds to the local buffer size that is set by VAXTPU. This parameter is 
optional. 


DESCRIPTION By default, the text you specify as a prompt is written in the PROMPT-AREA 

on the screen. The PROMPT—AREA is established with the built-in procedure 

SET (PROMPT-AREA_). See SET (PROMPT-AREA, . . . ) for more 

information. If no PROMPT-AREA is defined, the text specified as a prompt 
is displayed at the current location on the device pointed to by SYSSOUTPUT 
(usually your terminal). 

If READ-LINE terminates because it reaches the limit of characters specified 
as the second parameter, the last character read becomes the last key. 
Example 2 is a procedure that tests for the last key entered in a prompt 
string. 

When you invoke VAXTPU with the /NODISPLAY qualifier, terminal 
functions, such as screen display and key definitions, are not used. The 
built-in procedure READ—LINE calls the LIB$GET—INPUT routine to issue 
a prompt to SYS$INPUT and accept input from the user. A read done this 
way does not terminate when the number of keys you specified as the second 
parameter ([integer]) are entered. However, string2 contains the number of 
characters specified by the integer parameter and LAST—KEY contains the 
value of the key that corresponds to the integer specified as the last key to 
be read, except in the following cases. If the read is terminated by CTRL/Z, 
LAST—KEY has the value CTRL/Z. If the read is terminated by a carriage 
return before the specified integer limit is reached, LAST—KEY has the value 
of the RETURN key. 

If you are running VAX/VMS with line editing turned on (this is the default), 
line editing commands, such as CTRL/A and the arrow keys, are available 
for use on command lines of EVE or the EDT Keypad Emulator. You can use 
line editing commands to edit your response to the READ—LINE prompt. 
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EXAMPLES 

D ny.prompt :« REAO.LINE ('Enter key dellnltion:', 1) 

This assignment statement displays the text "Enter key definition:" in the 
PROMPT-AREA, and stores the first character of the user's response in the 
variable my—prompt. 

Q SAMPLE PROCEDURE 

The following procedure prompts for 3 characters and stores them in the 
variable my—input. It then tests for the last key entered. 

PROCEDURE user.test.laatkey 
LOCAL my.key, Ik; 

my.input :> READ.LINE ('Enter 3 characters;', 3); 

!Press the keys 'ABC 
my .key LAST.KEY; 

IF my.key - KEY.NAME CO 
THEN 

MESSAGE CC key") ELSE MESSAGE ('error') ENDIF; 

ENDPROCEDURE 

g] SAMPLE PROCEDURE 


The following procedure is used by commands that prompt for integers. The 
procedure returns true if prompting worked or was not needed; it returns false 
otherwise. The value that is returned is returned as an output parameter. 


! Parameters: 

! old.number Old Integer value - input 

i new.number Ne« integer value - output 

I prompt.string Text of prompt - input 
! no.value.message Message printed if user bits RETURN to 
! get out of the command - input 
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PROCEDURE user.proDpt.ntunber (old.number, new.number, 

prompt.strlng, no.value.message) 

! String read alter prompt 
LOCAL read_llne_Btring; 

new_naaber :■ old.number; 

IF old.number < 0 
THEN 

raad_llna_Btring :■ READ.LIKE (prompt.strlng); 

EDIT (read.line.string, TRIM); 

IF read.line.string ■ ” 

THEN 

MESSAGE (no.Talue.me8sage); 
new.number ;■ 0; 

RETURN (0); 

ELSE 

TRANSLATE (read.line.string. "1". "I"); IChange lowercase 1 to «1 
new.number ;• INT (read.line.8tring); 

IF (new.number = 0) and (read.line.string <> "O”) 

THEN 

MESSAGE (FAO ("Don't understand !AS", read.line.8tring)); 
RETURN (0); 

ELSE 

RETURN (1): 

ENDIF; 

ENDIF; 

ELSE 

RETURN (1); 

ENDIF: 

ENDPROCEDURE 
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REFRESH 

Repaints the whole screen. It erases any extraneous characters, 
such as those caused by noise on a communication line, and 
repositions the text so that the screen represents the last known 
state of the editing context. 

FORMAT 

REFRESH 

parameters 

None. 

DESCRIPTION 

REFRESH causes a redrawing of every line of every window that is mapped 
to the screen. The prompt area is erased. This built-in procedure causes the 
screen to change immediately. Even if REFRESH is issued from within a 
procedure, the action takes place immediately. VAXTPU does not wait until 
the entire procedure is completed to execute the built-in procedure REFRESH. 


VAXTPU reissues escape sequences as appropriate to do any of the following: 

• To set the scrolling region 

• To set the keypad into applications mode 

• To get the video attributes in a known state 

• To clear the screen of a DEC—CRT 

• To reset the graphic character sets 


REFRESH repaints the whole screen. See UPDATE for a description of how 
to update a single window to make it reflect the current state of the buffer 
associated with the window. 


EXAMPLES 



Q REFRESH 

This command causes the screen manager to repaint the whole screen so that 
it reflects the current internal state of the editor. 

Q SAMPLE PROCEDURE 


The following procedure removes the contents of the message—buffer and 
then repaints the whole screen. 

PROCEDURE U8er_repalnt 
ERASE (message.bulfer); 

REFRESH; 

ENDPROCEDURE 
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REMAIN 

Returns a pattern that matches any string starting at the current 
character position and continuing to the end of the current line. 

FORMAT 

pattern := REMAIN 

parameters 

None. 

DESCRIPTION 

The pattern that is returned does not cross line boundaries. 

EXAMPLES 

Q patl ;• LINE_BEGIN A 

■!' A REMAIN 

Q SAMPLE PROCEDURE 

This assignment statement stores in the variable patl a pattern that matches 
all lines that have an exclamation point at the beginning of the line. 


The following procedure moves toward the end of the buffer, stopping at the 
first uncommented line. 

PROCEDURE usar_mov«_skip_conffleiit8 
ON.ERROR 

I This statsDsnt causes us to stop moving 
! vertically as soon as the search lor a comment 
! on the current line fails 
RETURH 
ENDON.ERROR 

I 

! Hove to beginning of line first 
MOVE_HORIZONTAL(-CURRENT_OFFSET); 

! comment character must be at the beginning of the line 
comment.pattem :> ANCHOR A '!' A REMAIN; 

MOVE_VERTICAL (1); 

LOOP 

comment_range :• SEARCH (comment.pattem, FORWARD); 

MOVE_VERTICAL (1); 

ENDLOOP; 

ENDPROCEDURE 
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REMOVE_KEY_MAP 

Removes key maps from key-map lists. 


FORMAT REMOVE_KEY_MAP (stringh string2i, ALL]) 


parameters string 1 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key-map list containing the key map to be removed. 

stringZ 

A quoted string, or a variable name representing a string constant, that 
specifies the name of the key map to be removed from the key-map list. 

ALL 

This keyword is an optional argument. It specifies that all the key maps with 
the name specified by string2 in the key-map list are to be removed. 


DESCRIPTION This built-in procedure removes one or more key maps from a key-map 

list. If the optional keyword ALL is specified, all of the key maps with the 
specified name in the key-map list are removed from the list. Otherwise, only 
the first entry with the specified name is removed. 


RETURN 

STATUS 


TPU$_NOKEYMAP 

WARNING 

TPU$_NOKEYMAPLIST 

WARNING 

TPU$_KEYMAPNTFND 

WARNING 

TPU$_EMPTYKMLIST 

WARNING 


Second argument is not a defined key 
map. 

Second argument is not a defined key 
map. 

The key map listed in the second 
argument is not found. 

The key-map list specified in the first 
argument contains no key maps. 


EXAMPLE 

SAMPLE CODE 


In the following example, a key-map list, named KEYMAP_LIST, is created. 
The call to SHOW (KEY_MAP_LISTS) shows that the key-map list contains 
three key maps: KEYMAP_1, KEYMAP_2, and KEYMAP_1 again. After the 
call to REMOVE_KEY_MAP, the call to SHOW (KEY_MAP_LISTS) shows 
that the key-map list contains only KEYMAP_2. 
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ua«rtk«yaap_l :• CREATE_KEY_MAP Cksymap.l"); 
ui*r$k«]r>ap_2 :> CREATE.KEY.MAP (■'keymap_2''); 

uaar$kay>ap_llat :• CREATE.KEY.MAP.LIST (”keymap_llat'', uaertkaymap.l, 

UBar$kaymap_2); 

AOD.KEY.HAP (usartkeynap.liat, "last”, uaertkeynap.l); 


SHOW (KEY_MAP.LISTS); 


REMOVE.KEY.MAP (userlkeTiiap.llat, uaerlkeymap.l, ALL); 


V SHOW (KEY_MAP_LISTS); 
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SAVE 


Writes the binary form of all currently defined procedures, variables, 
and key definitions to the section file you specify. 


FORMAT SAVE (string) 


parameter string 

A quoted string, a variable name representing a string constant, or 
an expression that evaluates to a string, that is a valid VAX/VMS file 
specification. You should supply a full VAX/VMS file specification, including 
device and directory. 


DESCRIPTION SAVE is used to add to or create VAXTPU section files. If you are adding 

to an existing section file, the new section file contains all of the items from 
the original section file and the new items from the current editing session. 
Section files enable VAXTPU interfaces to start up quickly because they 
contain the following items in binary form: 

• All compiled PROCEDURE ... ENDPROCEDURE statements. 

• Every variable created (only the variable's name is saved, not its contents). 

• Every key definition that binds a statement, procedure, program, or a 
learn sequence to a key. (This includes the comments that you add to key 
definitions.) 

• Every key map and key-map list created. 

When you use the built-in procedure SAVE during an editing session to 
add items to an existing section file, SAVE does not keep items that were 
established interactively with the built-in procedure SET (for example, margin 
settings for buffers, or setting the editor's shift key to something other than 
the PFl key.) 

You should use a full file specification as the string parameter for SAVE. 

If you do not supply a full file specification, VAXTPU uses the device and 
directory associated with the /SECTION qualifier. If you explicitly used 
/SECTION=full-file-spec to invoke VAXTPU, the device and directory 
you specified are used. If you did not provide a full file specification 
for /SECTION, or if you did not explicitly use /SECTION, the device 
and directory pointed to by the logical name TPUSECINI (by default, 
SYS$LIBRARY) are used. If you explicitly used /NOSECTION when invoking 
VAXTPU, the cunent device and directory are used if you do not provide a 
full file specification. 

The default file type is TPU$SECTION. 


RETURN 

STATUS 


TPU$_SAVEERROR 


ERROR 


The section cannot be created because 
of errors in context being saved. 
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EXAMPLE 

SAVE ('SYStLOGIN:mysectlon.TPUtSECTION■) 

This command, issued just before exiting from the editor, adds all of the 
procedure definitions, key definitions, and variables from your current editing 
session to the section file with which you invoked VAXTPU. The new file that 
you specify, SYS$LOGIN:mysection.TPU$SECTION, contains initialization 
items from the original section file and from your editing session. 

To invoke VAXTPU with the new, combined section file, enter the following 
command at the DCL level: 

t EDIT/TPa/SECTION>SYS$LOGIN;ayB«ction 
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SCAN 

Returns a pattern that matches the longest string of characters that 
does not contain any of the characters included in the parameter 
string. 

FORMAT 

pattern := SCAN (string) 

parameter 

string 

A quoted string, or a variable name representing a string constant, that 
contains the characters that you do not want to match. 

DESCRIPTION 

The pattern that is returned does not cross record (line) boundaries. The 
pattern starts at the current character position and continues to the end of 
the current line or until it finds one of the characters in the string used as a 
parameter. 

EXAMPLES 


D patl SCAN ('abc') 

This assignment statement stores a pattern that matches the longest string of 
characters that does not contain a, b, or c in patl. 

Q SAMPLE PROCEDURE 

The following procedure identifies parenthetical text within a single line. It 
moves the current character position to the beginning of the parenthetical 
text, if it exists. 


PROCEDURE user_llnd_parens 

Paren_text ;= ANYCC) ft SCAN O'): 

round_range := SEARCH (Paren.text, FORWARD, NO.EXACT); 

IF lound.range =0 ! No parentheses. 

THEN MESSAGE ('No parentheses found.'); 

ELSE POSITION (found.range); 

ENDIF 


ENDPROCEDURE 
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SCANL 

Returns a pattern that matches the longest string of characters that 
does not contain any of the characters included in the parameter 
string. SCANL crosses record (line) boundaries. 

FORMAT 

pattern := SCANL (string) 

parameter 

string 

A quoted string, or a variable name representing a string constant, that 
contains the characters that you do not want the pattern to match. 

DESCRIPTION 

SCANL is similar to SCAN. However, SCANL continues a pattern beyond 
the end of the line. A SCANL pattern starts at the current character position 
and continues beyond the end of the line until it finds one of the characters 
in the specified string or until it reaches an end-of-search condition. The 
end-of-search condition is the beginning of the buffer if the direction of the 
search is REVERSE or the end of the buffer if the direction of the search is 
FORWARD. 


EXAMPLES 

□ patl :« SCANL ('abc') 


This assignment statement stores in patl the longest string starting at the 
current character position that does not contain a, b, or c. 

Q SAMPLE PROCEDURE 


The following procedure identifies parenthetical text if it exists, and locates 
the current character position at the beginning of found__range. 


PROCEDURE u8er_llnd_parenB 


paren_text := ANYCC) <c SCANL ('('): 

found_range ;» SEARCH (Paren_text. FORWARD, NO.EXACT); 


IF lound.range • 0 ! No more parentheses. 

THEN MESSAGE (•No parentheses found.')I 
ELSE POSITION (found.range); 

ENDIF 

ENDPROCEDURE 
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SCROLL 

Moves the lines of text in the buffer up or down on the screen by 
the number of lines you specify. The cursor does not move but 
stays positioned at the same relative screen location. The current 
character position is different from the character position that was 
current before you issued the scroll command. SCROLL optionally 
returns an integer that indicates the number and direction of lines 
actually scrolled. (A negative number indicates the number of lines 
scrolled upwards; a positive number indicates the number of lines 
scrolled downwards.) The value of integer2 may differ from what 
was specified in integer). 

FORMAT 

|[integer2 :=1 SCROLL (window[, { ^ | integer!]) 

parameters 

window 

The window associated with the buffer whose text you want to scroll. 


integerl 

The signed (+/“) integer value that indicates how many lines you want the 
text to scroll. A positive integer causes the text in the window to scroll up 
from the bottom of the screen to the top. A negative integer causes the text in 
the window to scroll down from the top of the screen to the bottom. If you 
specify 0 as the integer value, no scrolling occurs. 


This parameter is optional. 


DESCRIPTION If you omit the second parameter, the text scrolls continuously until it reaches 

a buffer boundary or until you press a key. If the current direction of the 
buffer is FORWARD, the text scrolls to the end of the buffer. If the current 
direction of the buffer is REVERSE, the text scrolls to the beginning of the 
buffer. If you press a key that has commands bound to it, the scrolling stops 
and VAXTPU executes the commands bound to the key. 

You can scroll text only in a visible window. If the window is not currently 
visible on the screen, VAXTPU issues an error message. 

Note that SCROLL causes the screen to scroll immediately. It does not wait 
for the completion of a procedure to take effect. 

SCROLL does not work in the following cases: 

• If you have turned off the screen update flag with SET 
(SCREEN-UPDATE, OFF). 

• If you used the /NODISPLAY qualifier when invoking VAXTPU on an 
unsupported device. 

• If the window that you specify is not visible on the screen. 

When the scrolling is complete, the current character position (record and 
offset) is set to match the cursor position (screen line and column position). 
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After the scrolling stops, the cursor may be located to the right of the last 
character in the new current record. In this instance, any VAXTPU built-in 
procedure that requires a record offset (for example, CURRENT-OFFSET, 
MOVE-HORIZONTAL, MOVE-VERTICAL, MARK, and so on) causes the 
record to be blank-padded to the cursor location. 

If the screen you are using does not have hardware scrolling regions, the 
window being "scrolled* is repainted for each scroll that would have occurred. 
SCROLL (my—window, 3) repaints the window three times. 



RETURN 

STATUS 


TPU$_WINDNOTMAPPED WARNING 
TPU$_CONTROLC ERROR 


You are trying to scroll an unmapped 
window. 

You pressed CTRL/C to stop scrolling. 




EXAMPLES 

D SCROLL (Daln_wlndow,+10) 

This command causes the text of the buffer that is mapped to the main 
window to scroll up 10 lines. 

Q SCROLL (my.wlndow) 

This command causes the text in the buffer that is mapped to my—window 
to scroll in the direction to which the buffer is set untU it reaches a buffer 
boundary. 

Q SAttPLE PROCEDURE 


The following procedure scrolls the main buffer and returns the number of 
lines scrolled, until the user presses a key. 

PROCEDURE UMr_*croll_bull*r 
LOCAL ■crollad.linaa: 

MESSAGE ("Preas any Icay to atop acrolling... *); 
acrollad_lliiaa : • SCROLL (Daln_window); 
dimy_koy READ.KET 
RETURN acrollad_llnaa; 

ENDPROCEDURE; 
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SEARCH 


Looks for a particular arrangement of characters and returns a range 
that contains the matching characters in the current buffer. 


FORMAT range := 

SEARCH Ykeywordi [,keyword2J) 


parameters string 

The string that you want to match. 

pattern 

The pattern that you want to match. 

keyword 1 

You must use one of the following words: 

• FORWARD—Indicates a search in a forward direction. 

• REVERSE—Indicates a search in a reverse direction. 

keyword2 

The following keywords are optional. If you do not specify a third parameter, 

NO_EXACT is the default. 

• EXACT—Indicates that the characters SEARCH is trying to match must 
be exactly the same case (upper, lower, or mixed case) as the characters in 
the string or pattern that is used as the first parameter. 

• NO_EXACT—Indicates that the characters SEARCH is trying to match 
need not be the same case (upper, lower, or mixed case) as rite characters 
in the string or pattern that is used as the first parameter. 


DESCRIPTION A successful SEARCH returns a range. The range contains the characters 

in the current buffer that match the characters you specified with string or 
pattern. If SEARCH fails to find a match, a 0 is returned and an error is 
signaled. 

If you want the current character position to move to the beginning of the 
range returned by SEARCH, you must use the built-in procedure POSITION 
to move the cursor. 

To search for complex character arrangements, use a pattern rather than 
a string as the parameter for SEARCH. See Section 2 for a description of 
patterns. 

By default, the built-in procedure SEARCH uses the seek search mode of 
searching. For information on the modes of searching see Section 2. 
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RETURN 

STATUS 


TPU$_STRNOTFOUND WARNING Search for a string or pattern was 

unsuccessful. 


EXAMPLES 

D U8er_range SEARCH ('Ref lectlone of MONET', FORWARD, NO.EXACT) 

If you were searching a buffer in which the string 'Reflections of Monet' 
appeared, this assignment statement would store the characters 'Reflections of 
Monet' in the range user_range. The search would find a successful match 
even though the characters in the word Monet do not match in case, because 
you specified NO_EXACT. 

S SAMPLE PROCEDURE 


The following procedure searches for the word 'CHAPTER' appearing at the 
beginning of a line. If it finds it, it positions to the beginning of the string. If 
it doesn't find it, it writes an appropriate message in the message buffer. 

PROCEDURE usar.flnd.chap 

chap LINE_BEGIN b 'CHAPTER'; 

found_range ;> SEARCH (chap, FORWARD, NO.EXACT); 

IF found_range *0 ! No match found. 

THEN MESSAGE ('CHAPTER not found.'); 

ELSE POSITION (found.range); 

ENDIF 

ENDPROCEDURE 
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SELECT 

Returns a marker for the current character position in the current 
buffer. You must specify how the marker is to be displayed on 
the screen (no special video, reverse video, bolded, blinking, or 
underlined). 


The marker returned by SELECT indicates the first character position 
in a select range. The video attribute that you specify for the marker 
applies to all the characters in a select range. For information on 
creating a select range, see SELECT_RANGE. 

FORMAT 

marker := SELECT (keyword) 

parameter 

keyword 

Specifies how the marker that is returned is to be displayed on the screen. 
You must use one of the following keywords: 


• NONE—Applies no video attributes to marker. 

• BOLD—Causes the marker to be bolded. 

• BLINK—Causes the marker to blink. 

• REVERSE—Causes the marker to be displayed in reverse video. 

• UNDERLINE—Causes the marker to be underlined. 

DESCRIPTION 

SELECT returns a select marker that establishes the beginning of a select 
range. The select marker is positioned at the character position that is the 
current character position when the built-in procedure SELECT is executed. 
(The select marker is actually positioned between character positions, rather 
than on a character position). A select range includes all the characters 
between the select marker and the current position. 


Only one select marker per buffer can be active at any one time. If a buffer is 
associated with more than one visible window, the select range is displayed 
in only one window (the current or most recent window). 

If the buffer in which you are selecting text is associated with the current 
window, as you move from the select marker to another character position 
in the same buffer, all the characters over which you move the cursor are 
included in the select range, and the video attribute that you specify for the 
select marker is applied to the characters in the range. The video attribute of 
a selected character is not visible when you are positioned on the character, 
but once you move beyond the character, the character is displayed with the 
attribute you specify. 

If the current character is deleted, the marker moves to the nearest character 
position. The nearest character position is determined in the following way: 

1 If there is a character position on the same line to the right, the marker 
moves to this position, even if the position is at the end of the line. 
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2 If the line on which the marker is located is deleted, the marker moves to 
the first position on the following line. 

If you are positioned at the select marker and you insert text, the select 
marker moves to the first character of the inserted text. You can move one 
column past the last character in a line. (With free cursor motion, you can 
move even further beyond the last character of a line.) However, if you 
establish a select marker beyond the last character in a line, no video attribute 
is visible for the marker. 


RETURN 

STATUS 


TPU$_ONESELECT WARNING Select is already active. 


EXAMPLES 

□ ■alact.mark ;> SELECT (NONE) 

This assignment statement places a marker at the cunent character position. 
Because NONE is specified, no video attributes are applied to a select range 
that has this marker as its beginning. 

Q 8el«ct_iMrk_under :« SELECT (UNDERLINE) 

This assignment statement places a marker at the current character position. 
Any characters included in a select range that has this marker as its beginning 
are underlined. 


S SAMPLE PROCEDURE 


The following procedure creates a bold marker that is used as the beginning 
of a select region. As you move the cursor, the characters that you 
select are bolded. To turn off the selection of characters set the variable 
user^vJbeginning-Dfselect to 0. 

1 + 

I BOLD SELECTED TEXT 

!- 

PROCEDURE user_itart_B«lect 

u>er_v_beglnning_ol_select :> SELECT(BOLD); 

ENDPROCEDURE 
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SELECT_RANGE 


Returns a range that contains all the characters between the marker 
established with the built-in procedure SELECT and the current 
character position. SELECT-RANGE does not include the character 
at the end position in the selected range. 


FORMAT range := SELECT_RANGE 


parameters None. 


DESCRIPTION If you select text in a forward direction, the select range includes the marked 

character and all characters up to but not including the current character. 

If you select text in a reverse direction from the marker, the select range 
includes the current character and all characters up to but not including the 
marked character. 

SELECT-RANGE is used in conjunction with SELECT to allow the user to 
mark a section of text for treatment as an entity. 

The procedure for selecting a section of text is the following: 

1 Use the built-in procedure SELECT to place a marker at the beginning of 
the section you want to select (for example, ml := SELECT (NONE)). 

2 Mark the characters that you want in the select region by moving from 
character to character with the cursor. 

3 When all of the text is selected, create a range that contains the selected 
text (for example, rl := SELECT-RANGE). 

4 Stop the selection of characters by setting the marker that marks the 
beginning of the range to null (ml := 0). 


RETURN 

STATUS 


TPU$_NOSELECT WARNING There is no select active. 

TPU$_SELRANGEZERO WARNING Select range contains zero selected 

characters. 


EXAMPLES 

Q select.l :• SELECT.RANGE 

This assignment statement puts the range for the currently selected characters 
in the variable select—1. 
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Q SAMPLE PROCEDURE 


The following procedure shows the use of SELECT-RANGE multiple times in 
the same procedure. 

PROCEDURE usar.salect 

I Start a selact ragion 

uaer.salect.posltion :• SELECT (REVERSE); 

MESSAGE (■Salaction startad.*); 

! Mora 8 rows and craata a salact ragion 
MOVE_VERTICAL (6); 

SRI SELECT_RANGE; 

! Mova 6 rows and craata anotbar salact ragion 
MOVE_VERTICAL (6); 

SR2 :• SELECT_RANGE: 

! Stop tba salaction by sotting the salact markor to 0. 

vsar.seloct.positlon ;• 0; 

ENDPROCEDURE 
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SEND 

Passes data to a subprocess. 

FORMAT 

( buffer 'I 

SEND (1 range \ r process) 

( string J 

parameters 

buffer 

The buffer whose contents you want to send to the subprocess. 


range 

The range whose contents you want to send to the subprocess. 


String 

The string that you want to send to the subprocess. 


process 

The process to which you want to send data. 

DESCRIPTION 

All output from the subprocess is stored in the buffer that was associated with 
the subprocess when you created it. See CREATE—PROCESS. Your editing 
stops until the process responds to what is sent. 

If you specify a buffer or a range as the data to pass to a subprocess, the lines 
of the buffer or range are sent as separate records. 

RETURN 

STATUS 

TPU$_NOPROCESS WARNING Subprocess that you tried to send to 

has already terminated. 

TPU$_SENDFAIL WARNING Unable to send input to a subprocess. 

For a buffer: 

TPU$_NOSENDBUF WARNING Input buffer is same as output buffer. 

For a range: 

TPU$_CONTROLC ERROR The execution of the command you 

sent terminated because you pressed 
CTRL/C. 
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EXAMPLES 

□ SEND ('DIRECTORY', usar.proceia) 

This command sends the DCL command DIRECTORY to the subprocess 
named user_process. The subprocess must already be created with the built- 
in procedure CREATE—PROCESS so that the output can be stored in the 
buffer associated with the subprocess. 

Q SAMPLE PROCEDURE 




The following procedure uses the built-in procedure SEND to pass a 
command to a subprocess in which the DCL MAIL utility is running. The 
command to be sent to the subprocess is obtained with the built-in procedure 
READ-LINE. 

PROCEDURE nall.anbp 

i CREATE A BUFFER AND A WINDOW THAT A SUBPROCESS CAN RUN IN 
T_mail_l»ulfar CREATE_BUFFER ("Ball.buffer"); 

T_Ball_wlndow :• CREATE_WINDOW (1, 22, ON); 

!Hap tba Ball window to tba acretn 
UNNAP (MAIN.WINDOW); 

MAP (T_Ball_window, v_nall_bulfer); 

I CREATE A SUBPROCESS AND SEND "MAIL* AS THE FIRST COMMAND 
pi :» CREATE_PROCESS {v_mail_bulfar, "MAIL"); 

t POSITION TO THE SUBPROCESS AND USE READ.LINE FOR NEXT COMMAND 
POSITION (v_Ball_window}; 
al READ_LINE ( ''Ball_aubp> ", 20); 

SEND (al, pi); 

ENDPROCEDURE 
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SEND- 

EOF 


Uses features of the VAX/VMS Mailbox Driver to send an end-of-file 
message (IO$_WRITEOF) to a subprocess. 

FORMAT 

SEND_EOF (process) 

parameter 

process 

The process to which the end-of-file is being sent. 

pg3CRIPTION end-of-file causes an outstanding read from a subprocess to be completed 

with an SS$_ENDOFFILE status. See the VAX/VMS I/O Reference Volume for 
more information on the Write End-of-File message. 

RETURN 

STATUS 

TPU$—SENDFAIL WARNING Unable to send input to a subprocess 

TPU$_NOPROCESS WARNING No subprocess to send to 


EXAMPLE 


SEND_E0F (sub.procl) 


This command sends an end-of-file to sub_procl. 
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SET 


FORMAT 

parameters 


Allows you to establish or to change certain features of a VAXTPU 
session. SET requires a keyword as its first parameter. The 
keyword indicates which feature of the editor is being set. You 
can set the mode for entering text, the text that is to be displayed 
on certain parts of the screen, the direction of a buffer, the status of 
a buffer, and so on. 


SET (keyword, parameter [,.. J) 


keyword 

The keyword used as the first parameter specifies which feature is being 
established or changed. Following are the valid keywords for SET: 

• AUTO-REPEAT 

• BELL 

• DEBUG 

• EOB-TEXT 

• FACIUTY-NAME 

• FORWARD 

• INFORMATIONAL 

• INSERT 

• JOURNAUNG 

• KEY-MAP-LIST 

• MARGINS 

• MAX-LINES 

• MESSAGE-FLAGS 

• NO-WRITE 

• OUTPUT-JFILE 

• OVERSTRIKE 

• PAD 

• PERMANENT 

• PROMPT-AREA 

• REVERSE 

• SCREEN-UPDATE 

• SCROLUNG 

• SELF-INSERT 

• SHIFT-KEY 
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• STATUS_LINE 

• SUCCESS 

• SYSTEM 

• TAB-STOPS 

• TEXT 

• TIMER 

• UNDEFINED-KEY 

• VIDEO 

• WIDTH 

Each of these keywords and the parameters that follow them are described 
on the following pages. The descriptions of the keywords are organized 
alphabetically. 

parameter . . . ] 

The number of parameters following the first parameter varies according to 
the keyword you use. The parameters are listed in the FORMAT section of 
the applicable keyword description. 


DESCRIPTION The built-in procedure SET can be used by both the programmer creating an 

editing interface and by the person using the interface. The programmer can 
establish certain default behavior and screen displays for an editing interface. 
The user can change the default behavior and do some simple customizing of 
an existing VAXTPU interface with the built-in procedure SET. 
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SET (AUTO-REPEAT_) 

FORMAT 

SET (AUTO-REPEAL keyword) 

parameters 

AUTO-REPEAT 

This keyword refers to the repetition of keystrokes as long as you hold down 
a key. 

keyword 

The valid keywords are ON or OFF: 

ON—Continues to generate the character indicated by a keystroke until the 
key is released. 

OFF—Requires a separate keystroke for each character generated. 


DESCRIPTION VAXTPU sends an escape sequence to the terminal to set AUTO-REPEAT on 

or off. 


The auto—repeat feature affects all keyboard keys on the VTIOO series of 
terminals except the following: 

• the SET—UP key 

• the ESC key 

• the NO SCROLL key 

• the TAB key 

• the RETURN key 

• the CTRL key and another key 

The auto—repeat feature affects all keyboard keys on the VT200 series of 
terminals except the following: 

• the keys FI, F2, F3, F4, F5 

• the RETURN key 

If you want to slow down the movement of the cursor, you can use SET 
(AUTO—REPEAT, ... ) within a procedure that causes cursor motion. 
Because of the time the terminal requires to process the escape sequence 
that VAXTPU sends it, if you turn AUTO—REPEAT off before moving the 
cursor and on after the movement, you slow down the cursor movement. 
You may find it useful to slow the cursor motion at the top or bottom of a 
window. The sample procedure in the Example section shows how to do this. 
See Example 2. 
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SET (AUTO-REPEAT, . . . ) 


EXAMPLES 

□ SET (AUTO_REPEAT. OFF) 

This statement turns AUTO_REPEAT off. 

Q SAMPLE PROCEDURES 


The following procedures show how to turn AUTO-REPEAT off and on to 
slow the cursor movement. 

! Two procedures that slow the scrolling action 

PROCEDURE user_slow_up_arrow 
SET (AUTO_REPEAT, OFF); 

MOVE_VERTICAL (-1); 

SET (AUTO_REPEAT. ON); 

ENDPROCEDURE 

PROCEDURE user_slow_down_arrow 
SET (AOTO_REPEAT, OFF); 

MOVE.VERTICAL (1); 

SET (AUTO_REPEAT, ON); 

ENDPROCEDURE 
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SET (BELL . .. ) 


SET (BELL . . . ) 


FORMAT SET (BELL, keywordi, keyword2) 



parameters BELL 

This keyword refers to the terminal bell. 

keywordi 

The valid keywords are ALL or BROADCAST: 

ALL—Indicates that keyword2 (ON or OFF) applies to all messages. 
BROADCAST—Indicates that keyword2 applies to broadcast messages only. 

keyword2 

The valid keywords are ON or OFF: 

ON—Causes the terminal bell to ring when a message is written to the 
message window. 

OFF—Turns off the audible signal of the terminal bell. 


DESCRIPTION When the bell is on, the terminal bell rings to signal the fact that a message 

is being written to the message window. When you use ALL as keywordi, 
internal VAXTPU messages, as well as broadcast messages, cause the terminal 
bell to ring. To cause VAXTPU messages of success and informational 
severity level to be written to the message buffer, you must have used the 
built-in procedure SET ({INFORMATIONAL I SUCCESS), ON). When you 
use BROADCAST as keywordi, only broadcast messages, such as MAIL 
notifications and REPLY messages, cause the bell to ring. 

SET (BELL, ALL, (ONIOFF)) affects the setting of SET (BELL, BROADCAST, 
(ON I OFF)). If you want the behavior of broadcast messages to be different 
from other messages, use the built-in procedure SET (BELL, BROADCAST, 
(ONIOFF)) after using SET (BELL, ALL, (ONIOFF)). 

Note that VAXTPU causes the bell to ring as a signal that a message is being 
written to the message window, not as an interpretation of a bell character 
in the message text. Bell characters in the message text are not interpreted, 
they are displayed as an uninterpreted control character. Positioning to the 
message window, and moving the cursor to a bell character in the message 
text does not cause the terminal bell to ring. 

You can also use DCL commands to affect the display of broadcast messages 
within VAXTPU. If you use the command SET TERMINAL/NOBROADCAST 
at the DCL level, no broadcast messages are sent to your terminal. The 
DCL command SET BROADCAST allows you to enable or disable certain 
classifications of broadcast messages. 




DEFAULT The bell is OFF by default. 
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SET (BELL . . . ) 


EXAMPLES 

Q SET (BELL, BROADCAST, ON) 

This statement causes the terminal bell to ring when a broadcast message is 
being written to the message window. 

s SAMPLE PROCEDURE 


The following procedure uses SET (BELL, ALL, ON) to cause the bell to ring 
for the message that is being sent in the second statement. After the message 
is written, the bell is turned off. SET (BELL, BROADCAST, ON) is used to 
cause broadcast messages to ring the terminal bell. 

PROCEDURE U8er_ring_bell (m8g_string) 

SET (BELL, ALL. ON); !Tum bell on 

MESSAGE (m8g_8trlng); IWrite message text to message buffer 
SET (BELL, ALL, OFF); ITurn bell off 

SET (BELL, BROADCAST.ON); !Tum bell on for broadcast messages 
EHDPROCEDURE 
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SET (DEBUG_) 


SET (DEBUG, . . . ) 


FORMAT 


SET (DEBUG, keywordi, 1. { ) J) 


parameters DEBUG 

This keyword refers to a program that helps you locate VAXTPU 
programming errors. 

keywordi 

The valid keywords are ON, OFF, and PROGRAM: 

ON—Causes a debugger to do single-step debugging. Each time the line 
number in a VAXTPU program changes, the debugger is invoked. 

OFF—Disables single—step debugging. 

PROGRAM—Indicates that the user has written a program that is used to 
locate VAXTPU programming errors. 

String 

Either the name of a procedure or a program. 

If the name of a procedure follows the keyword ON, the debugger is invoked 
each time the procedure is called. 

If the name of a procedure follows the keyword OFF, the debugger removes 
the breakpoint that was set at the procedure. 

If a program follows the keyword PROGRAM, the program is used as a 
user-written debugger. 

keyword2 

The keyword ALL can be specified if keywordi is OFF. The statement SET 
(DEBUG, OFF, ALL) causes all breakpoints to be removed. 


RETURN 

STATUS 


TPU$_NOCURRENTBUF WARNING There is no current buffer. 
TPU$_NONAMES WARNING No names match the one requested. 


EXAMPLES 

□ SET (DEBUG, ON, "user.remove’) 

This Statement causes the debugger to be activated each time the procedure 
user_remove is called. 
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SET (DEBUG. . . . ) 


Q SET (DEBUG, PROGRAM, "user.dabugger") 

This Statement causes the user-written program user-debugger to be called as 
the program to help locate programming errors. 
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SET {EOB_TEXT_) 


SET (EOB. 

-TEXT_) 

FORMAT 

SET (EOB-TEXT, buffer, string) 

parameters 

EOB-TEXT 

This keyword refers to the text displayed at the end of a buffer. This text is 
merely a visual marker in a buffer and does not become part of the file that is 
created when a buffer is saved. 


buffer 

The buffer in which the text for the end-of-buffer is being set. 


String 

The text that is displayed to indicate the end-of-buffer. 

DEFAULT 

The default end-of-buffer text is [EOB]. 


EXAMPLE 


SET (EOB.TEXT, main.bufler, "[END OF MAIN EDITING BUFFER]") 

This statement causes [END OF MAIN EDITING BUFFER] to be displayed as 
the end-of-buffer text for main—buffer. 


4-169 





VAXTPU Built-In Procedures 

SET (FACILITY_NAME_) 

SET {FACILITY_NAME, . . . ) 

FORMAT 

SET (FACILITY-NAME, string) 

parameters 

FACILITY-NAME 

This keyword refers to the facility name that is the first item in a message 
generated by VAXTPU. 

String 

The string that you specify as the facility name for messages. The maximum 
length of this name is 10 characters. 

RETURN 

STATUS 

TPU$_FACTOOLONG WARNING Name specified is longer than maximum 

allowed. 

EXAMPLE 

SET (FACILITY_NAME. "ne» 

r_edltor") 


This statement causes new_editor to be used as the facility name in messages. 
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SET (FORWARD, . . . ) 


SET (FORWARD. . . . ) 

FORMAT 

SET (FORWARD, buffer) 

parameters 

FORWARD 

This ke)rword refers to the direction of the buffer. FORWARD means to go 
toward the end of the buffer. 

buffer 

The buffer whose direction you want to set. 

DESCRIPTION 

This feature is use by interfaces to keep track of direction for searching or 
movement. 

DEFAULT 

The default direction for a buffer is FORWARD. 

EXAMPLE 



SET (FORWARD, my.bulfer) 


This Statement causes the direction of the buffer to be toward the end of the 
buffer. 


4-171 





VAXTPU Built-In Procedures 

SET (INFORMATIONAL, . . . ) 


SET (INFORMATIONAL, . . . ) 

FORMAT 

SET (INFORMATIONAL, keyword) 

parameters 

INFORMATIONAL 

This keyword refers to informational messages that VAXTPU writes. 

keyword 

The valid keywords are ON and OFF: 

ON—Causes the informational messages to be written 

OFF—Suppresses the display of informational messages 

DESCRIPTION 

If you specify a section file when invoking VAXTPU (either by default, 
or by using the qualifier /SECTION=file-spec), VAXTPU may not display 
informational messages. You can cause informational messages to be written 
by using SET (INFORMATIONAL, ON). 

If you use the qualifier /NOSECTION when invoking VAXTPU, informational 
messages are written by default. 

When you are developing VAXTPU programs, the informational messages 
help you find errors in your program, so it is a good idea to use the 
built-in procedure SET (INFORMATIONAL, . . . ) to cause the messages to be 
displayed. 

See Appendix C for a list of the VAXTPU informational messages. 


EXAMPLE 


SET (INFORMATIONAL, OFF) 


This statement causes the display of informational messages to be turned off. 
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SET (INSERT, . . . ) 

FORMAT 

SET (INSERT, buffer) 

parameters 

INSERT 

This keyword refers to the mode of entering text. INSERT means that 
characters are added to the buffer in front of the current character position. 
See also the description of the built-in procedure SET (OVERSTRIKE). 


buffer 

The buffer whose mode of text entry you want to set. 

DEFAULT 

The default mode for text entry is INSERT. 

EXAMPLE 


SET (INSERT, my.buller) 


This Statement causes the characters that you add to the buffer to be added in 
front of the current character position. 
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SET (JOURNALING, . . . ) 


SET (JOURNALING, . . . ) 

FORMAT 

SET (JOURNALING, integer) 

parameters 

JOURNALING 

This keyword refers to the journal file that enables you to recover your editing 
session if it is interrupted abnormally. 


integer 

The integer that you specify determines how frequently records are written to 
the journal file. The value of this integer must be between 1 and 10. 

DESCRIPTION 

VAXTPU provides a 500 byte buffer for journaling keystrokes. If journaling is 
enabled, a write to the journal file occurs when the buffer is full. This built-in 
procedure allows you to determine the frequency with which records are 
written to the journal file; the lower the integer you specify, the more often 
journal records are written to disk. 


A value of 1 causes a record to be written for approximately every 10 keys 
pressed. A value of 10 causes a record to be written for approximately every 
125 keys. If you are entering only text (rather than procedures that are bound 
to keys), the number of keystrokes included in a record is greater: for a value 
of 1, a record is written for approximately every 30 to 35 keystrokes; for a 
value of 10, a record is written for approximately every 400 keystrokes. 

RETURN 

STATUS 

TPU$_MINVALUE WARNING Argument is less than minimum 

allowed. 


TPU$_MAXVALUE WARNING Argument is greater than maximum 

allowed. 


EXAMPLE 

SET (JOURNALING, 1) 


This statement causes records to be written to the journal file frequently. 
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SET {KEY_MAP_LIST_) 


SET {KEY_MAP_UST, . . . ) 

FORMAT 

SET (KEY-MAP-LIST, string [, buffer}) 

parameters 

KEY-MAP-LIST 

Keyword that refers to the key-map list that you bind to a buffer. 


String 

A quoted string, or a variable name representing a string constant, that 
specifies the key-map list that you bind to a buffer. 


buffer 

Buffer to which you bind the specified key-map list. The default is the current 
buffer to which you are positioned. 

DESCRIPTION 

This built-in procedure binds a specified key-map list to a buffer. If the buffer 
is not specified, the default is to bind the key-map list to the current buffer in 
use. A key-map list can be associated with only one buffer at a time. 

DEFAULT 

The default key-map list is TPU$KEY_MAP_LIST. 

RETURN 

STATUS 

TPU$_NOKEYMAPLIST WARNING Attempt to access an undefined 

key-map list. 


EXAMPLES 

□ SET (KEY_MAP_LIST. •tpul.k«y_map_li«t«) 


This Statement binds the key-map list called tpu$_key_map_list to the 
current buffer. 
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SET (MARGINS, . . . ) 


SET (MARGINS, . . . ) 


FORMAT SET (MARGINS, buffer, integerl, integer2) 

parameters MARGINS 

This ke)word refers to the left and right margins of a buffer. 

buffer 

The buffer in which the margins are being set. 

integerl 

The column at which the left margin is set. 

mteger2 

The column at which the right margin is set. 


DESCRIPTION This built-in procedure allows you to change the left and right margins of a 

buffer. The margins for a buffer are set to 1 for the left margin and 80 for 
the right margin when the CREATE—BUFFER is used. The built-in procedure 
FILL procedure uses the margin settings when it is Riling the text of a buffer. 

This built-in procedure controls the buffer margin setting even if the terminal 
width or window width is set to something else. 

The value of the left margin must be at least 1, and less than or equal to 
the right margin value. The value of the right margin must be less than 
the maximum record size for the buffer. You can use the built-in procedure 
GET—INFO (buffer, "'record—size*) to find out the maximum record size of a 
buffer. 

If you want to use the margin settings of a buffer in a user-written procedure, 
GET—INFO (buffer, ‘left—margin") and GET—INFO (buffer, 'right—margin") 
return the values of the margin settings. 


DEFAULT The default left margin is 1, and the default right margin is 80. 


RETURN 

STATUS 


TPU$_BADMARGINS 


WARNING 


Left must be greater than right; both 
must be greater than zero. 


VAXTPU Built-In Procedures 

SET (MARGINS, . . . ) 


EXAMPLES 

□ SET (MARGINS, ny.bulfer, 1. 133) 

This Statement causes the margins of the buffer represented by the variable 
my—buffer to be changed. The left margin of the buffer is 1 and the right 
margin is 132. 

2 SET (MARGINS, CURRENT.BOFFER, 10, 70) 

This statement causes the margins of the current buffer to be changed to left 
margin 10 and right margin 70. 
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SET (MAX_LINES_) 


SET (MAX 

-LINES, . . . ) 

FORMAT 

SET (MAX—LINES, buffer, integer) 

parameters 

MAX-LINES 

This keyword refers to the maximum number of lines a buffer can contain. 


buffer 

The buffer for which you are setting the maximum number of lines. 


integer 

The maximum number of lines for the buffer. 

DESCRIPTION 

If you exceed the maximum number of lines for a buffer, VAXTPU deletes 
lines from the beginning of the buffer to make room for any lines that exceed 
the maximum. 

If you use 0 as the number of lines for the buffer, this feature is turned off 
and VAXTPU does not check for the maximum number of lines. 

DEFAULT 

The default maximum number of lines is 0 (in other words, this feature is 
turned off). 

RETURN 

STATUS 

TPU$_MINVALUE WARNING Argument less than minimum allowed. 

EXAMPLE 


SET (HAX_LINES. maisaga.bufler, 20) 

This Statement causes the maximum number of lines for the message-buffer 
to be 20. Only the most recent lines of messages are kept. 
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SET (MESSAGE_FLAGS_) 



SET (MESSAGE--.FLAGS, . . . ) 



FORMAT SET (MESSAGE-FLAGS, integer) 


parameters MESSAGE-FLAGS 

This keyword refers to the message flags in the $PUTMSG System Service. 

integer 

The value specified for the $PUTMSG Message Codes. Table 4-3 lists the 
message codes. 




DESCRIPTION The following table shows the Message Codes for $PUTMSG: 


Table 4-3 Message Codes for $PUTMSG 


Bit 

Value 

Meaning 

0 

1 

Include text of message. 


0 

Do not include text of message. 

1 

1 

Include message identifier. 


0 

Do not include message identifier. 

2 

1 

Include severity level indicator. 


0 

Do not include severity level indicator. 

3 

1 

Include facility name. 


0 

Do not include facility name. 


If you do not set a value for the message flags, the default message flags for 
your process are used. Setting the message flags to 0 does not turn off the 
message text. It causes VAXTPU to use the default message flags for your 
process. In addition to setting the message flags from within VAXTPU, you 
can set them at the DCL level with the command SET MESSAGE. This is the 
only way you can turn off all message text. See the VAX/VMS DCL Dictionary 
for information on the DCL command. 


RETURN 

STATUS 


TPU$_FLAGTRUNC 


WARNING Message flag values must be less than 
or equal to 15. 
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SET (MESSAGE_FLAGS_) 


EXAMPLES 

□ SET (MESSAGE_FLAGS, 2) 

This Statement causes the message identifier to be the only item included in 
VAXTPU messages. The integer 2 sets bit 1. 

S SET (MESSAGE_FLAGS, 5) 

This statement causes the message text (bit 0 = 1) and the severity level 
indicator (bit 2 = 4) to be included in VAXTPU messages. The integer 5 sets 
bits 2 and 0. 
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SET (NO_WRITE, . . . ) 


SET (NO. 

-WRITE, . . . ) 

FORMAT 

SET (NO-WRITE, buffer, [keyword]) 

parameters 

NO-WRITE 

This keyword specifies that no output file should be created from the contents 
of a buffer upon exiting from VAXTPU even if the contents of the buffer have 
been modified. 


buffer 

The buffer whose contents you do not want written out when you exit from 
VAXTPU. 


keyword 

The keywords ON and OFF are optional: 


ON—Causes the buffer you name not to be written out when you exit from 
VAXTPU. 


OFF—^Allows you to change a buffer from the no-write state to the default 
state. By default, any modified buffers are written out upon exiting from 
VAXTPU. 

DEFAULT 

By default, the buffer is written, if modified. 


EXAMPLES 

□ SET (NO.KKITE, my.buller) 


This Statement causes my-Jbuffer not to be saved in a file upon exiting from 
VAXTPU. 

Q SET (NO.WBITE, my.buller, OFF) 

This Statement changes the state of myJbuffer from no-write. The contents of 
the buffer are written out upon exiting from VAXTPU if the buffer has been 
modified. 


4-181 


VAXTPU Built-In Procedures 

SET (OUTPUT_FILE_) 


SET (OUTPUT-FILE, . . . ) 

FORMAT 

SET (OUTPUT-FILE, buffer, string) 

parameters 

OUTPUT-FILE 

This keyword refers to the file specification that is to be created from the 
contents of a buffer when you exit from VAXTPU. 

buffer 

The buffer whose contents are written to the file you specify. 

String 

The file specification for the file being written out. 

DESCRIPTION 

If you do not modify the buffer for which you have specified an output file, 
that file is not written out upon exiting from VAXTPU. 

If you have set a buffer to NO—WRITE, a file is not written out upon exiting 
from VAXTPU even though you have specified a file specification for the 
contents of the buffer with the built-in procedure SET (OUTPUT—FILE, ... ). 

DEFAULT 

The default output file is the input file name and the highest existing version 
number for that file plus 1. 

EXAMPLE 



SET (OUTPUT_FILE. paste.buffer. 'newlile.txt') 

This Statement causes the output file for paste_buffer to be newfile.txt. 
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SET (OVERSTRIKE, . . . ) 


SET (OVERSTRIKE, . . . ) 

FORMAT 

SET (OVERSTRIKE, buffer) 

parameters 

OVERSTRIKE 

This keyword refers to the mode of text entry. OVERSTRIKE means that 
the characters that you add to the buffer replace the characters in the buffer 
starting at the current character position and continuing for the length of the 
text that you enter. See also the description of the built-in procedure SET 
(INSERT). 


buffer 

The buffer whose mode of text entry you want to set. 

DEFAULT 

The default mode of text entry is INSERT. 

EXAMPLE 


SET (OVERSTRIKE, my.buller) 


This Statement sets the mode for text entry in my—buffer to be overstrike. 
Characters that you enter replace characters already in the buffer starting at 
the current character position and continuing for the length of the text that 
you enter. 
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SET (PAD, . . . ) 


SET (PAD, 

... ) 

FORMAT 

SET (PAD, window, keyword) 

parameters 

PAD 

This keyword refers to padding screen lines with blanks rather than ending 
a line at the end of a record. V^en video attributes are applied to a padded 
window, the window has an even or "boxed" appearance on the right side. 


window 

The window in which lines are padded. 


keyword 

The valid ke3words are ON and OFF: 


ON—Causes VAXTPU to display blanks after the last character of a record 
so that the screen line extends to the right side of the window. If there are 
not enough lines in a buffer to fill an entire window, VAXTPU displays blank 
lines (according to the video setting of the window) from the end-of-buffer 
line to the end of the window. 


OFF—Causes the display of lines on the screen to stop at the last character of 
a record. When video attributes are applied to the window, the window has 
a ragged appearance on the right side. 

DESCRIPTION 

By default, VAXTPU ends a line on the screen at the end of a record. 

The default behavior of not padding the screen gives maximum editing 
performance. You can change the default with SET (PAD, . . . ) for special 
visual effects. The records in the buffer are not padded; only the display lines 
have the padding. 

DEFAULT 

By default, there is no blank padding on the right. 


EXAMPLE 


SET (PAD, second.wlndow, ON); 

SET (VIDEO, second_wlndow, REVERSE); 

The first statement causes second-window to be blank padded. The second 
statement causes second-window to be displayed in reverse video. The 
window will have an even right margin. 
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SET (PERMANENT, . . . ) 


SET (PERMANENT, . . . ) 

FORMAT 

SET (PERMANENT, buffer) 

parameters 

PERMANENT 

This keyword specifies that a buffer cannot be deleted. 

buffer 

The buffer that is not to be deleted. 

DESCRIPTION 

Once you use SET (PERMANENT, buffer) to make a buffer permanent, you 
cannot reset the buffer so that it can be deleted. 

DEFAULT 

By default, the buffer can be deleted, it is not PERMANENT. 

EXAMPLE 


SET (PERMANENT, master.buller) 

This Statement causes master_buffer to be set to a permanent buffer. 
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SET (PROMPT-AREA_) 


SET (PROMPT_AREA, . . . ) 


FORMAT SET (PROMPT—AREA, integer 1, integer2, keyword) 


parameters PROMPT-AREA 

This keyword refers to an area on the screen in which the prompts generated 
by the built-in procedure READ-LINE are displayed. 

integer 1 

The screen line number at which the PROMPT-AREA starts. 

integerZ 

The number of screen lines in the PROMPT—AREA. 

keyword 

You must use one of the following keywords: 

• NONE—Applies no video attributes to the characters in the 
PROMPT-AREA. 

• BOLD—Causes the cheiracters in the PROMPT—AREA to be bolded. 

• BLINK—Causes the characters in the PROMPT—AREA to blink. 

• REVERSE—Causes the characters in the PROMPT—AREA to be displayed 
in reverse video. 

• UNDERLINE—Causes the characters in the PROMPT-AREA to be 
underlined. 


DESCRIPTION If the prompt area overlaps a line of a window that is visible on the screen, 

the line is erased when the built-in procedure READ—LINE is executed. 
When the execution of READ—LINE is completed, the line is restored. If the 
prompt area does not overlap any windows, the prompt area continues to 
display the READ—LINE prompt and your input, until new information is 
sent to the prompt area. 

If you have a multiple-line prompt area and your terminal has hardware 
scrolling capabilities, the first prompt appears on the last line of the prompt 
area and as subsequent prompts are issued, the previous prompts scroll up to 
make room for new ones. If there are more prompts than there are prompt 
lines, the extra prompts are scrolled out of the window. 

If your terminal doesn't have hardware scrolling capabilities, prompts are 
displayed starting at the first line down and start over at the fhst prompt line, 
if and when the prompt area is filled. 
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SET (PROMPT-AREA, ... ) 


EXAMPLE 


SET (PROMPT_AKEA, 24, 1, REVERSE) 

This Statement causes the prompt area to be screen line number 24. It is one 
line and is displayed in reverse video. 
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SET (REVERSE, . . . ) 


SET (REVERSE, . . . ) 

FORMAT 

SET (REVERSE, buffer) 

parameters 

REVERSE 

This keyword refers to the direction of the buffer. REVERSE means to go 
toward the beginning of the buffer. 

buffer 

The buffer whose direction you want to set. 

DESCRIPTION 

This feature is use by interfaces to keep track of direction for searching or 
movement. 

DEFAULT 

The default direction for a buffer is FORWARD. 

EXAMPLE 

SET (REVERSE, my.buffer) 

This statement causes the direction of the buffer to be toward the beginning 
of the buffer. 
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SET (SCREEN-UPDATE_) 


SET (SCREEN-UPDATE, . . . ) 

FORMAT 

SET (SCREEN^UPDATE, keyword) 

parameters 

SCREEN-UPDATE 

This ke 3 rword refers to the process of sending characters and cursor 
movement sequences to the screen to ensure that the screen reflects the 
current internal state of any buffer displayed on the screen. The VAXTPU 
screen manager handles this function. 


keyword 

The valid keywords are ON and OFF: 

ON—Causes the screen manager to send characters and cursor movement 
sequences to update the screen. 

OFF—Causes the screen manager to hold screen updating until SET 
(SCREEN-UPDATE, ON) is issued. 

EXAMPLE 


SET (SCREEN.UPDATE, OFF) 

This statement causes screen updating to be turned off. When you design 
an editing interface, you may want to use this statement to prevent some 
intermediate processing steps from appearing on the screen. 


4-189 




VAXTPU Built-In Procedures 

SET (SCROLLING, . . . ) 


SET (SCROLLING, . . . ) 


FORMAT SET (SCROLLING, window, keyword, integer 1, 

integer2, integers) 


parameters SCROLLING 

This keyword refers to the upward or downward movement of existing lines 
in a window to make room for new lines at the bottom or top of the window. 
When a window is scrolled, the cursor position remains in the same column, 
but the screen line that the cursor is on may change. 

window 

The window in which the scrolling limits are being set. 

keyword 

The valid keywords are ON or OFF: 

ON—Causes scrolling of the text in a window to be turned on. 

OFF—Causes scrolling of the text in a window to be turned off. The screen is 
completely repainted each time a scroll would otherwise take place. 

integer 1 

The offset from the top screen line of a window. The offset identifies the top 
limit of an area in which the cursor can move as it tracks the current character 
position. If the cursor is forced to move above this screen line to track the 
current character position, lines in the window move downward so that the 
cursor stays within the limits of the cursor area. If you reach the beginning of 
the buffer, the text is no longer scrolled. 

integer2 

The offset from the bottom screen line of a window. The offset identifies the 
bottom limit of an area in which the cursor can move as it tracks the current 
character position. If the cursor is forced to move below this screen line to 
track the current character position, lines in the window move upward so that 
the cursor stays within the limits of the cursor area. If you reach the end of 
the buffer, the text is no longer scrolled. 

integers 

The number indicating how many lines from the top or the bottom of the 
cursor area the cursor should be positioned when a window is scrolled. The 
cursor area is delimited by integerl and integer2. For example, if the bottom 
of the cursor area is screen line 14 and integers has a value of 0, when text 
is scrolled upward, the cursor is positioned on screen line 14. However, if 
integers has a value of S, the cursor is positioned on screen line 11. 


DESCRIPTION This built-in procedure is used to modify the scrolling action of a window. 

The default integer values are SET (SCROLLING, window, ON, 0, 0, 0,). 
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SET (SCROLLING, . .. ) 

DEFAULT 

The default cursor limit for scrolling at the top of the screen is the first line of 
the window; the default cursor limit for scrolling at the bottom of the screen 
is the bottom line of the window. 

RETURN 

STATUS 

TPU$_BADVALUE ERROR Arguments are out of minimum and 

maximum bounds. 


EXAMPLES 

□ SET (SCROLLING, new.wlndow, ON, 0, 0, 2) 


This Statement causes new_window to scroll in the following manner: when 
the cursor reaches either the top or the bottom of the window, lines are 
moved off the screen to make room for new lines. The cursor is positioned 
on a line that is offset 2 lines from either the top or the bottom of the window 
each time a scroll occurs. 

S SET (SCROLLING, new.wlndow, ON, 0, 0, 20) 

If new_window is 21 lines long, this command causes new_window to 
scroll in the following manner: when the cursor reaches either the top or the 
bottom of the window, lines are moved off the screen to make room for new 
lines. The cursor is positioned at the top of the window if you are scrolling 
forward and at the bottom of the window if you are scrolling backward. This 
setting for scrolling presents an entire window of new text each time a scroll 
occurs. 


4-191 





VAXTPU Built-In Procedures 

SET (SELF_INSERT_) 


SET (SELFJNSERT, . . . ) 


FORMAT SET (SELF-INSERT, string, keyword) 


parameters SELF-INSERT 

Keyword that specifies whether printable characters are inserted when entered 
if no procedures are bound to them. 

String 

A quoted string, or a variable name representing a string constant, that 
specifies the key-map list that is active. 

keyword 

The valid keywords are ON and OFF: 

ON—Causes the printable characters to be inserted when no procedures are 
bound to them, while the specified key-map list is active. 

OFF—Causes the UNDEFINED-KEY procedure to be called when these 
characters are entered. 


DESCRIPTION This built-in procedure allows you to control how undefined printable 

characters are treated. If SELF-INSERT is set ON, undefined printable 
characters are inserted into the current buffer at the current cursor position. 
If SELF—INSERT is set OFF, printable characters for which there are no 
definitions in any key maps in the key-map list bound to the current buffer 
are considered undefined. These undefined keys cause either the message 
"key has no definition" to be displayed, or some user-defined action to occur. 
See the description of the built-in procedure SET (UNDEFINED—KEY, . . . ). 


DEFAULT The default result for entering printable characters not bound to any 

procedure is that the characters are inserted. The default condition 
for SET (SELF-INSERT, . .. ) is ON. The default condition if SET 

(SELF-INSERT_) is OFF, is to call the UNDEFINED-KEY procedure. 

See the description of the built-in procedure SET (UNDEFINED—KEY, .. . ). 


RETURN 

STATUS 


TPU$_NOKEYMAPLIST 


WARNING Attempt to access an undefined 
key-map list 
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SET (SELF-INSERT_) 


EXAMPLE 

SAMPLE PROCEDURE 


PROCEDURE toggla.tall.lnicrt 

LOCAL curr«nt_k«jr_map_list; 

curreiit.key_>ap_li8t :« GET.INFO (CURRENT.BUFFER, "key.map.list"); 

IF GET.INFO (current_key_map_llst, "self.insert”) 

THEN 

SET (SELF.INSERT, current.key.inap.li8t. OFF) 

ELSE 

SET (SELF.INSERT. current.key.map.li8t. ON) 

ENDIF; 

ENDPROCEDURE; 


This procedure toggles the ON and OFF setting of SELF-INSERT for the 
key-map list bound to the current buffer. 
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SET (SHIFT-KEY_) 

FORMAT 

SET (SHIFT-KEY, keyword[, string]) 

parameters 

SHIFT-KEY 

This keyword refers to VAXTPU's shift key (by default PFl), not the key 
marked SHIFT on the keyboard. 

keyword 

A VAXTPU keyname for a key. 

String 

A quoted string, or a variable name representing a string constant, that is 
a key-map list name. This optional argument specifies the key-map list in 
which the shift key is used. If the key-map list is not specified, the key-map 
list associated with the current buffer is used. 


DESCRIPTION The VAXTPU shift key is similar to the GOLD key in EDT. This shift key 

allows you to assign two commands to one key: one is used when the key 
is pressed by itself, and the other is used when the key is pressed after the 
defined shift key. A shift key setting that you establish with the built-in 
procedure SET (SHIFT-KEY, . . . ) stays in effect only for the current session. 
Use the built-in procedure DEF1NE_J^Y if you want to make a permanent 
key definition. 

Only one VAXTPU shift key can be active at a time. The VAXTPU 
SHIFT—KEY can be any key other than the following: 

• the SHIFT key 

• the ESC key 

• the SCROLL key on the VTIOO keyboard 

• the keys FI, F2, F3, F4, and F5 on the VT200 keyboard 

• the COMPOSE CHARACTER key on the VT200 keyboard 

By default, PFl is the VAXTPU shift key. If you want to use PFl for another 
purpose, use SET (SHIFT-KEY, ... ) to define a key other than PFl as 
VAXTPU's shift key. 

If you do not want a shift key for your editing interface, you can cause PFl to 
be undefined with the following command: 

SET (SHIFT_KEY, KEY.NAME (PFl. SHIFT_KEY)) 
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EXAMPLE 

SET {SHIFT_KEY, PF4. 


VAXTPU Built-In Procedures 

SET {SHIFT_KEY_) 


*tputk«y_map_list'') 

This Statement causes the keypad key PF4 to be defined as the shift key 
for the editor. This definition holds true in the default key-map list called 
tpu$key_map_Jist. 
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SET (STATUS-LIIME_) 


FORMAT SET (STATUS—LINE, window, keyword, string) 


parameters STATUS-LINE 

This keyword refers to the last line in a window. You can use the status line 
to display regular text or you can use it to display status information about 
the window. 

window 

The window in which the status line is being modified. 

keyword 

Specifies the video attribute for the STATUS-LINE. You must use one of the 
following keywords: 

• NONE—Applies no video attributes to the characters on the 
STATUS-LINE. 

• BOLD—Causes the characters on the STATUS—LINE to be bolded. 

• BLINK—Causes the characters on the STATUS—LINE to blink. 

• REVERSE—Causes the characters on the STATUS—LINE to be displayed 
in reverse video. 

• UNDERLINE—Causes the characters on the STATUS—LINE to be 
underlined. 

• SPECIAL-GRAPHICS—Causes the characters on the STATUS-LINE 
to display graphics characters, such as a solid line. These characters 
are from the DEC Special Graphics Set (also known as the VTIOO Line 
Drawing Character Set). For more information on the special graphics that 
are available, see the appropriate programming manual for your video 
terminal. 

String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the text to be displayed on 
the STATUS-LINE. To remove a status line, use a null string (") as this 
parameter. 


DESCRIPTION You can establish a status line for a window when you create a window. 

CREATE—WINDOW requires you to specify whether the status line is ON 
(used for status information) or OFF (used as a regular text line). When you 
specify ON, the default status line is displayed in REVERSE video; it contains 
the name of the buffer associated with the window and the name of the file 
associated with the buffer, if there is one. 
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If the window that you use as a parameter for SET (STATUS-LINE, .. . ) 
already has a status line (either because you specified ON for the status line 
parameter in the built-in procedure CREATE—WINDOW, or because you used 
a previous SET (STATUS—LINE, .., ) for the window), the video attribute 
that you specify is added to the video attribute of the existing status line 
unless you specify NONE. (NONE overrides the other video keywords and 
specifies that there are to be no video attributes for the status line.) The string 
you specify as the last parameter replaces the text of an existing status line. 

If there is no status line for a window, the built-in procedure SET 
(STATUS—LINE, ... ) establishes a status line on the last visible screen 
line of the window. The status line has the video attribute and the text you 
specify. Adding a status line reduces the number of screen lines available for 
text by one line. 

To remove a status line, use a null string (") as the last parameter. 


The default for the status line (ON or OFF) is determined by the built-in 
procedure CREATE-WINDOW. 


EXAMPLES 

□ SET (STATUS_LINE, ny.window, REVERSE, "MAIN BUFFER, newlile.txt”) 

This Statement causes the status line in my—window to be displayed in reverse 
video with the buffer specified as MAIN BUFFER and the file specified as 
newfile.txt. 

B SET (STATUS_LINE, my.window, NONE, ■■) 

Causes the status line in my—window to be removed by setting the final 
parameter to a null string. 

B SAMPLE PROCEDURE 


The following code draws a solid line across the status line. 

y :• “qqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqqq" + 
■qqqqqqqqqqqqqqqqqqqqq": 

X ;• CREATE_WINDOW (1, 20, OFF) 

MAP (x, current.buller) 

SET (8TATUS_LINE, X, SPECIAL.GRAPHICS, y) 
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SET (SUCCESS, . . . ) 

FORMAT 

SET (SUCCESS, keyword) 

parameters 

SUCCESS 

This keyword refers to success messages that VAXTPU writes. 

keyword 

The valid keywords are ON and OFF: 

ON—Causes the success messages to be written. 

OFF—Suppresses the display of success messages. 

DESCRIPTION 

By default VAXTPU writes success messages to the message buffer. If you 
want to suppress the display of these messages, you can use this built-in 
procedure. 

See Appendix C for a table of the VAXTPU messages and their severity levels. 


EXAMPLE 


SET (SUCCESS, OFF) 

This statement turns off the display of success messages. 


VAXTPU Built-In Procedures 




SET (SYSTEM, ... ) 


SET (SYSTEM, . . . ) 


FORMAT 

SET (SYSTEM, buffer) 

o 

parameters 

SYSTEM 

This keyword refers to the status of a buffer. SYSTEM means that it is a 
system buffer rather than a user buffer. 

buffer 

The buffer that is being set as a system buffer. 


DESCRIPTION 

Once you make a buffer a system buffer, you cannot reset the buffer to be a 
user buffer. 

This built-in procedure allows programmers who are building an editing 
interface to distinguish their system buffers from buffers that the user creates. 

o 

DEFAULT 

By default, the buffer is a user buffer. 


EXAMPLE 


SET (SYSTEM, mtiaaga.bulfer) 

This Statement causes message-buffer to be set as a system buffer. 
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SET (TAB_STOPS_) 



SET (TAB- 

-STOPS, . . . ) 


FORMAT 

SET (TAB-STOPS, buffer, | 1 ) 

\ integer J 


parameters 

TAB-STOPS 

This keyword refers to the tab stops in a buffer. 



buffer 

The buffer in which the tab stops are being set. 



String 

A string of numbers (each separated from the next by a space), which are 
considered actual tab stop settings. The minimum value for a tab stop setting 
is 1 and the maximum value is 65535. The maximum number of tab stops 
that you can include in the string is 100. You must list the tab stops in the 
string in ascending order ('3 6 9 12"). 



integer 

The integer that you enter is considered an interval between tab stops rather 
than an actual tab stop setting. If you enter the integer 4, tab stops occur 
every 4 columns. The minimum value for the integer is 1 and the maximum 
value is 65535. 


DESCRIPTION 

The default tab stops are set to an interval of every eight characters. This 
built-in procedure allows you to change the tab stops to actual column 
positions or to equal intervals other than eight. 

On any terminals or printers that have tab settings different from those you 
specify with this built-in procedure, the file does not appear the same as it 
does when viewed using VAXTPU. This built-in procedure does not affect the 
hardware tab settings of your terminal. 

y 

DEFAULT 

The default tab stops are set every 8 character positions. 


RETURN 

STATUS 

TPU$_INVTABSPEC WARNING Bad third argument 



U 
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SET (TAB_STOPS, .. . ) 


EXAMPLES 

D SET (TAB.STOPS, CURRENT.BUFFER, 4) 

This Statement causes the tab stops in the current-buffer to be set at intervals 
of 4. 

0 SET (TAB.STOPS, CURRENT.BUFFER. "4 8 12 16") 

This statement causes the tab stops in the current—buffer to be set at columns 
4, 8, 12, and 16. 






4-201 


VAXTPU Built-In Procedures 

SET (TEXT, . . . ) 


SET (TEXT, . . . ) 


FORMAT SET (TEXT, window, keyword) 


parameters TEXT 

This keyword refers to the way in which text is displayed in a window. 

window 

The window in which the mode of display is being set. 

keyword 

The valid keywords are BLANK-TABS, GRAPHIC-TABS, and 

NO-TRANSLATE. The default is BLANK-TABS. 

• BLANK—TABS—Displays tabs as blank spaces. 

• GRAPHIC—TABS—Displays tabs as special graphic characters so that the 
value of each tab stop is obvious. 

• NO—TRANSLATE—Causes every character that is read from the keyboard 
to be sent directly to the screen without any translation. You should use 
this keyword with caution because it may cause unpredictable results if 
you do not fully understand the translations that are done by default. 


DEFAULT By default, the text is set to BLANK—TABS (tabs are displayed as blank 

spaces). 


EXAMPLES 

□ SET (TEXT, CURRENT.WINDOW, GRAPHIC.TABS) 

This Statement causes the text in main—window to be displayed with special 
characters indicating tab characters. 

Q SAMPLE PROCEDURE 


The following procedure shows a use of the NO—TRANSLATE keyword. 
Notice that the window is set to this state temporarily, and that the 
default setting for the window is reset as soon as the function for which 
NO—TRANSLATE is used is finished executing. 
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SET (TEXT, . . . ) 


! If jour terminal has a printer hooked up to the printer port, 
! the folloving procedure allowa you to perform a PRINT SCREEN 
I function. 

PROCEDURE near.prlnt 

! Set elndow to NO.TRANSLATE to allow the eecape lequence 
! to paat to the printer. Note that thie procedure doesn't send 
! a form-feed. 

SET (TEXT, message.wlndow, NO.TRANSLATE); 

MESSAGE (ASCII (27) * '[i'); 

t Put back the window the way it was 
SET (TEXT, message.wlndow, BLANK.TABS); 

ERASE (message.buffer); 

ENDPROCEDURE 
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SET (TIMER, . . . ) 

FORMAT 

SET (TIMER, keyword, [ string]} 

parameters 

TIMER 

This keyword refers to messages that are to be written to the prompt area at 
one-second intervals. 


keyword 

The valid keywords are ON and OFF: 

ON—Causes the message that you specify to be written to the prompt area. 
OFF—Turns off the display of timed messages in the prompt area. 


String 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is displayed in the prompt area. The 
maximum length of the message is 15 characters. The message is displayed 
in the last 15 character positions of the prompt area. If ON is specified and 
a string was never specified for the last argument, the timer puts out the 
message "working". If ON is specified and a string was specified previously, 
the string is saved and is used as the default. 

DESCRIPTION 

The timer puts out messages at one-second intervals while you are executing 
procedures or editing actions that are bound to a key. The message is written 
out to the prompt area and then erased to clear the prompt area for the next 
message. 

DEFAULT 

The timer is ON by default. 

EXAMPLE 

SET (TIMER, ON, "Executing") 

This statement causes the message 'Executing" to be written to the prompt 
area while you are executing a VAXTPU procedure. 


4-204 


VAXTPU Built-In Procedures 

SET (UNDEFINED-KEY_) 


SET (UNDEFINED^KEY_) 


FORMAT 


SET (UNDEFINED-KEY, string 1 


, string2 
, buffer 
, range 
, program 
, learn 


) 


parameters UNDEFINED-KEY 

This keyword refers to the action taken when an undefined key-map key is 
input. 

String 1 

A quoted string, or a variable name representing a string constant, that 
specifies the key-map list for which this procedure is called. 

optional third parameter 

This parameter specihes the action on an undefined key. If the parameter is a 
string, buffer, or range, it is compiled. 


DEFAULT 

The default procedure for an undefined key is to display the message, 'key 
has no definition'. If the third parameter is not given, the action on an 
undefined key is to reset it to the default. 

RETURN 

STATUS 

TPU$_NOKEYMAPLIST WARNING Attempt to access an undefined 

key-map list 

EXAMPLE 


SAMPLE CODE 

The following code causes the default undefined key message to be displayed 
when an undefined key is entered. 


IF GET.INFO Ctpntkey.map.list*, ’undallned.kay'') <> 0 

THEN 

SET (UNDEFINED.KEY. "tpu$k«y_a»p_ll«t"); 

ENDIF; 
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SET (VIDEO, . . . ) 


SET {VIDEO, . . . ) 


FORMAT SET (VIDEO, window, keyword) 

parameters VIDEO 

This keyword refers to the video attributes of a window. 

window 

The window in which a video attribute is being set. 

keyword 

You must use one of the following keywords: 

• NONE—Applies no video attributes to the characters in the window. 

• BOLD—Causes the characters in the window to be bolded. 

• BLINK—Causes the characters in the window to blink. 

• REVERSE—Causes the characters in the window to be displayed in 
reverse video. 

• UNDERLINE—Causes the characters in the window to be underlined. 


DESCRIPTION Video attributes for a window are cumulative. The window assumes the 

video attribute of each video keyword that you use with SET (VIDEO, . . . ) 
during an editing session. If you want to change the video attribute of a 
window, and you do not want the cumulative effect of previous attributes, 
use SET (VIDEO, window, NONE) before specifying the new attribute. SET 
(VIDEO, window, NONE) turns off all video attributes for a window. 

Note that the built-in procedure SET (VIDEO, ... ) does not affect the status 
line of a window. You can specify a video attribute for a status line with the 
built-in procedure CREATE—WINDOW (by default, the keyword ON gives a 
window a status line in REVERSE video), or with the built-in procedure SET 
(STATUS-LINE, . . . ). If you use SET (VIDEO, . . . ) to change the video 
attributes of a window, you may also want to use SET (STATUS—LINE, . . . ) 
to change the video attributes of the status line, if one exists for the window. 
When the window and the status line have different video attributes, the 
status line can be used to separate multiple windows on the screen, or to 
highlight status information. 


DEFAULT By default, there are no video attributes for a window. This is the state in 

which VAXTPU is most efficient at screen management. 
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SET (VIDEO, . . . ) 


EXAMPLE 

SET (VIDEO. CURRENT.WINDOW, REVERSE); 

SET (VIDEO. CURRENT.WINDOW. UNDERLINE); 

These statements cause the current window to be displayed in reverse video 
and with underlining. 
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SET (WIDTH, . . . ) 


SET (WIDTH, . . . ) 

FORMAT 

SET (WIDTH, window, integer) 

parameters 

WIDTH 

This keyword refers to the width of a window. 


window 

The window in which the width is being set. 


integer 

The value that specifies the width of the window. 

DESCRIPTION 

If the screen width is 80 columns and if a SET (WIDTH, .. . ) command 
causes a window to become wider than the screen, VAXTPU changes the 
screen width to 132 colunms. 

If the screen width is 132 columns and a SET (WIDTH, ... ) command causes 
a window to be less than 81 columns, VAXTPU changes the screen size to 80 
if all of the other windows are also less than 81 columns wide. 

If you exceed the value set for the width of the window when entering text, 
VAXTPU displays a diamond sjrmbol in the rightmost column of the screen 
to indicate that there is text beyond the diamond symbol that is not visible 
on the screen. You cannot make VAXTPU use multiple lines to display a line 
that is longer than the width of a window. 

DEFAULT 

By default, the width of a window is the same as the physical width of the 
terminal when the window is created. 

RETURN 

STATUS 

TPU$_BADVALUE ERROR Arguments are out of minimum and 

maximum bounds. 

EXAMPLE 

SET (WIDTH, CURRENT.WINDOW, 133) 

This statement causes the current wrindow to be 132 columns wide. 
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o 


SHIFT 


SHIFT 

Changes the relative position of text that is displayed in a window 
on the screen. The text in the window is shifted to the right or to 
the left. The shift applies to any buffer associated with the window 
that you specify. SHIFT optionally returns an integer. 


FORMAT 

|[integer2 :=1 SHIFT (window, integer 1) 


parameters 

window 

The window on the screen in which the shift in the position of the text is 
visible. 

integerl 

The signed (+/“) integer that specifies how many columns to shift the text. A 
positive integer causes the text to shift from the right to the left so that you 
can see text beyond the right edge of the window. 

A negative integer causes the text to shift from the left to the right so that 



you can see text beyond the left edge of the window. If the first character in 
the line of text is already in column 1, then using a negative integer to shift 
to the right has no effect. 

If you specify 0 as the value, no shift takes place. 


DESCRIPTION 

Use the built-in procedure SHIFT when the text in a window has gone 
beyond the right margin (indicated by the diamond symbol in the rightmost 
column). By shifting the text in the window from the right to the left, you 
can view text that was beyond the right edge of the window. 

o 


Because SHIFT commands are cumulative during an editing session, this 
built-in procedure optionally returns a value in integer2. This positive integer 
represents the cumulative shift value from the right to the left. 


SHIFT causes the entire window to be repainted. If you execute the built-in 
procedure SHIFT within a procedure, the screen is not updated to reflect 
the shift until the procedure has finished executing and control has returned 
to the screen manager. If you want the screen to reflect changes before the 
entire program is executed, you can force the immediate update of a window 
by adding an UPDATE statement to the procedure. 


o 
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SHIFT 


EXAMPLES 

D SHIFT (user.window, +6) 

This Statement causes the text displayed in user-window to be shifted 5 
columns to the left. 

S SHIFT (CnmREKT.WIHDOW. -6) 

This statement causes the text displayed in the current-window to be shifted 
5 columns to the right. (If the text was not previously shifted from the right 
to the left, this command has no effect.) 
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SHOW 


Displays information about VAXTPU data types and the current 
settings of attributes that can be applied to certain data types. See 
also the description of the built-in procedure GET_INFO. 


FORMAT SHOW ({ keyword 1 i 

\ data type J 


parameters keyword 

The following are valid keywords: 

• BUFFER[S]—Displays information about all buffers aveulable to the editor. 

• KEY_-MAP_LIST[SI—Displays the names of all defined key-map lists, 
their key maps, and the number of keys defined in each key map. 

• KEY_MAPISJ—Displays the names of all defined key maps. 

• KEYWORDS—Displays all items in the internal keyword table. 

• PROCEDURES—Displays the names of all defined procedures. 

• SCREEN—Displays information about the terminal. 

• SUMMARY—Displays statistics about VAXTPU including the current 
version number. 

• VARIABLES—Displays the names of all defined variables. 

• WINDOW[SJ—Displays information about all windows available to the 
editor. 

data type 

For information on a particular item, enter the variable to which a VAXTPU 
data type is assigned. The valid data types for the parameters to the built-in 
procedure SHOW are as follows: 

• Buffer—Shows information about the buffer variable you specify. 

• Window—Shows information about the window variable you specify. 

• String—Shows information about the string variable you specify. 


DESCRIPTION VAXTPU looks for the variable SHOW—BUFFER and checks to see if it 

refers to a buffer. VAXTPU also looks for the variable INFO—WINDOW 
and checks to see if it refers to a window. If these two items exist when 
you call the built-in procedure SHOW, VAXTPU writes information to 
SHOW-BUFFER and displays the information on the screen in the window 
called INFO-WINDOW. 

You, or the interface you are using, must create the buffer variable 
SHOW^UFFER when you initialize the interface for the built-in procedure 
SHOW to work as expected. 


4-211 






VAXTPU Built-In Procedures 

SHOW 


If you create a window called INFO_WINDOW, VAXTPU associates 
SHOW-BUFFER with INFO_WINDOW and maps this window to the screen 
when there is information to be displayed. You can optionally create a 
different window in which to display the information from SHOW-BUFFER. 
In this case, you must associate SHOW—BUFFER with the window that you 
create and map the window to the screen when there is information to be 
displayed. 

Because this built-in procedure maps INFO-WINDOW to the screen, any 
interfaces layered on VAXTPU should provide a mechanism for unmapping 
INFO—WINDOW and returning the user to the editing position that was 
current before using the built-in procedure SHOW. 

VAXTPU always deletes the current text in the show buffer before inserting 
the new information. 


RETURN 

STATUS 


TPU$_NOSHOWBUF WARNING SHOW-BUFFER must exist to store the 

requested information. 


EXAMPLES 

□ SHOW (PROCEDURES) 

This statement displays on the screen a list of all the VAXTPU built-in 
procedures and the user-written procedures that are available to your editing 
interface. 

S SHOW (SUMMARY) 


When VAXTPU is invoked with the EDT Keypad Emulator and a user-written 
command file, the preceding statement generates a screen display similar to 
the following one: 

TPU Version VI Update 2 

Journal Ilia: WORKS:[USER]CHAP4.TJL;2 
Section file: SYSICOMMOM:[SYSLIB]EDTSECINI.TPUISECTI0N;1 
Timer Message; Executing 
6 System bullers and 1 User buffer 

65 calls to LIBSGET.VM, 10 calls to LIB$FREE_VM, 083606 bytes still allocated 


S SHOW (CURRENT_BUFFER) 


When you use the default interface for the EDT Keypad Emulator, the 
preceding statement may display information similar to the following for the 
CURRENT-BUFFER: 

Buffer: MAIN_BUFFER 
Name: MAIN Mapped to 1 window 

Input File: WORKS;[USER]TEXT.FIL;8 
Output File: 

Contains 12830 lines Max_llne8: 4204067206 Maximum line size; 084 characters 
Left Margin: 1 Right Margin; 80 Tabs every 8 columns 
System Forward Insert 
Key Map List: TPUSKEY.MAP.LIST 
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Q SHOW (KEy_MAP_LISTS) 


The preceding statement displays the names of all defined key-map lists, their 
key maps, and the number of keys defined in each key map. When you use 
the default interface EVE, the VAXTPU command SHOW (KEY_MAP_LISTS) 
displays information similar to the following: 

D«fin*d key nap liats: 

TPU$KEY_MAP_LIST contains tha following key naps: 

EVEtUSER.KEYS (0 keys defined) 

EVEtVT200_KEYS (14 keys defined) 

EVEtSTAHDARD.KEYS (29 keys defined) 

Total of 1 key map list defined 
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SPAN 

Returns a pattern that matches the longest string of characters that 
contains only characters appearing in the string used as a parameter. 

FORMAT 

pattern := SPAN (string) 

parameter 

string 

A quoted string, or a variable name representing a string constant, that 
contains the characters you want included in the pattern. 

DESCRIPTION 

SPAN must match at least one character or it fails. If SPAN finds a character 
on the current line that is not in its parameter string, it stops. Otherwise, 
it stops at the end of the current line. SPAN does not cross record (line) 
boundaries. 

EXAMPLES 


Q patl ;« SPAN ('0123456789') 

This assignment statement creates a pattern that matches the longest sequence 
of digits starting at the current character position. 

Q SAMPLE PROCEDUKE 


The following procedure removes all lines that contain an x, y, or z. 

PROCEDURE user.remove.xyz 

patl SPAN Cxyz'); 

LOOP 

8l SEARCH (patl. FORWARD): 

EXITIF si - 0; 

POSITION (si): 

ERASE_LINE: 

ENDLOOP 

ENDPROCEDURE 
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SPANL 

Returns a pattern that matches the longest string of characters that 
contains only characters appearing in the string used as a parameter. 

FORMAT 

pattern := SPANL (string) 

parameter 

string 

A quoted string, or a variable name representing a string constant, that 
contains the characters that you want in the pattern. 

DESCRIPTION 

SPANL is similar to SPAN. However, SPANL considers the end-of-line 
condition as a match and continues the pattern beyond the end-of-line. It 
continues the search for a pattern until it finds a character that does not 
appear in the string used as a parameter or until an end-of-search condition 
is found. The end-of-search condition is the beginning of the buffer if the 
direction of the search is REVERSE, or the end of the buffer if the direction of 
the search is FORWARD. 

SPANL must match at least one character or it fails. 


EXAMPLES 

□ patl :> SPANL (' ') 


This assignment statement stores a pattern in patl that matches the longest 
sequence of blank characters starting at the current character position and 
continuing to an end-of-search condition. 

Q pat2 := SPANL ('0123456789’) 

This assignment statement stores in pat2 a pattern that matches the longest 
sequence of digits starting at the current character position and continuing to 
an end-of-search condition. 

S pat3 :■ SPANL (■ABCDEFCHIJKLHNOPQBSTUVWXYZ') 

This assignment statement stores in pat3 a pattern that matches the longest 
sequence of the alphabetic characters listed in the parameter. If you use this 
pattern with the built-in procedure SEARCH, search starts at the current 
character position and continues to an end-of-search condition. If you specify 
an EXACT search, the characters must be uppercase for a successful match. 
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SPAWN 


Deassigns the terminal and then creates a VAX/VMS subprocess. 


FORMAT SPAWN [(string)] 


parameter string 

The command string that you want to be executed in the context of the 
subprocess that is created with this built-in procedure. 


DESCRIPTION SPAWN suspends your VAXTPU process and spawns a VAX/VMS 

subprocess. This built-in procedure is especially useful for running programs 
and utilities that take control of the screen (these programs cannot be run in 
a subprocess created with the built-in procedure CREATE—PROCESS). See 
Section 2.10 for a list of restrictions for subprocesses. 

After completing work in a subprocess created with SPAWN, you can return 
to your VAXTPU session with either the DCL command ATTACH or the DCL 
command LOGOUT. If you use the DCL command ATTACH, the subprocess 
is available for future use. If you use the DCL command LOGOUT, the 
subprocess is deleted. When you return to the VAXTPU session, the screen is 
repainted. 

If you specify a DCL command as the parameter for SPAWN, the command 
is executed after the subprocess is created. When the command completes, 
the subprocess terminates, and control is returned to the VAXTPU process. 

SPAWN was designed to allow you to leave a VAXTPU session, do other 
work in a VAX/VMS subprocess, and return to the VAXTPU session that 
you interrupted. Subprocesses created with SPAWN put you directly at the 
DCL level. These subprocesses are different than the subprocesses created 
with the built-in procedure CREATE—PROCESS. CREATE—PROCESS creates 
subprocesses within a VAXTPU session, and all of the output from the 
subprocesses goes into a buffer. 

See the description of the built-in procedure ATTACH in this section for 
information on moving control from one subprocess to another. See the 
VAX/VMS DCL Dictionary for more information on the characteristics of a 
spawned subprocess. 


EXAMPLES 

Q SPAWN 


This command spawns a VAX/VMS subprocess and puts your VAXTPU 
process "on hold." After completing work in the subprocess, you can return 
to your VAXTPU session by using the DCL command ATTACH or the DCL 
command LOGOUT. 
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Q SPAWN ('DIRECTORY') 

This command spawns a VAX/VMS subprocess and executes the DCL 
command DIRECTORY. When the command completes, you are returned 
to your VAXTPU session. 


a 

A 



4-217 



VAXTPU Built-In Procedures 

SPLIT_LINE 


SPLIT_LINE 


Breaks the current line before the current character position and 
creates two lines. 

FORMAT 

SPLIT_LINE 

parameters 

None. 

DESCRIPTION 

When you use SPLIT-LINE, the current character position remains on the 
same character, but that character is now the first character on the newly 
created line. The new line that is created is inserted directly after the former 
current line. 

The relative screen position of the line you are splitting may change as a 
result of this procedure. 

RETURN 

STATUS 

TPU$_NOCURRENTBUF WARNING You are not positioned in a buffer. 

TPU$_NOCACHE ERROR There is not enough memory to allocate 

a new cache. 


EXAMPLES 

Q SPLIT_LINE 


This command breaks the current line at the current character position and 
makes a new line. 

Q SAMPLE PROCEDURE 


The following procedure splits a line at the current character position. If the 
current character position is column 1, row 1, the procedure causes the screen 
to scroll. 

PROCEDURE ut«r.spllt.UM 
LOCAL old_posltlon, M«_po«ltion; 

SPLIT.LINE: 

IF (CURRENT_ROW • 1) AND (CURRENT.COLUMN - 1) 

THEN 

al<l_posltlon :> MARK (NONE); 

SCROLL (CURRENT.WINDOW, -1); 
n«w_poaltlon ;> MARK (NONE); 

IMake sure we scrolled before doing CURSOR.VERTICAL 
IF new.position <> old_posltion 
THEN 

CURSOR_VERTICAL (1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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STR 

Converts an integer to a string. 

FORMAT 

String := STR (integer) 

parameter 

integer 

The integer that you want to convert to a string. 

DESCRIPTION 

You can use this built-in procedure to store a string representation of an 
integer in a variable name. You can then use the variable name in operations 
that require string data types. See the description of the built-in procedure 
FAO for another method of generating a string representation of an integer. 

EXAMPLES 

D new_numb«rs :> STR (123) 


This assignment statement stores the string *123" in the variable 
new—numbers. 

Q SAMPLE PROCEDURE 


The following procedure uses the built-in procedure STR to convert the 
integer variaWe vl to a string so that your column and row position can be 
displayed in the message area. 

PROCEDURE usar.dlsplay.positlon 

t 1 :« GET.INFO (■•cond.wlndow, "currant.coluon''); 

MESSAGE ('Column: ' * STR (t1)); 

t 2 :» GET.INPO (8econd_window, "current.row"); 

MESSAGE ('Row; ' + STR (v2)); 

ENDPROCEDURE 
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SUBSTR 

Returns a string that represents a substring of a string or a range. 

FORMAT 

stringZ := SUBSTR |, integerl, integer2) 

parameters 

String 1 

The string that contains the substring. 


range 

The range that contains the substring. 


integerl 

The character position at which the substring starts. The first character 
position is 1. 


integer2 

The number of characters to include in the substring. 

DESCRIPTION 

You must specify both the character position at which to start the substring 
and the length of the substring. If you specify a larger number of characters 
for integer2 than are present in the substring, only the characters present are 
returned in string2. No error is signaled. 


EXAMPLES 

□ flle.type SUBSTR ('login.com', 7. 3) 


This assignment statement returns the string 'com' in the variable file—type. 
The substring starts at the seventh character position ('c') and contains 3 
characters ('com'). If you use a larger number for integer2, for example, 7, 
the variable file—type still contains 'com' and no error is signaled. 

Q SAMPLE PROCEDURE 


The following procedure capitalizes the first character in a string. The 
procedure ignores leading punctuation so that strings within quotes ('test') or 
within parentheses (test) can be capitalized. 
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! 

I Paraaeters: 

! 

I ay.strlng String to be capitalized - input/output 
PROCEDURE nser.initial.cap (ay.string) 

LOCAL 

I Initial anbstrlng ending at tint letter 
initial.letter, 

! Loop index need in eearcb for first letter 
inltial.index, 

I Length of ay.strlng parameter 
ay_Btrlng_lengtb, 

! Remainder of my.strlng after initial.letter 
rest.of.string; 
initlal.index :• 1; 

By.string.lengtb :• LENGTH (my.strlng); 
not.alpbabetic t Non-alpbabetic graphic characters 

[]{}-.+-'I\: 

LOOP 

initial.letter :■ SUBSTR (my.strlng, 1. initlal.index); 
EZITIF initlal.index • my.string.length; 

EXITIF index (not.alpbabetic, 

SUBSTR (my.strlng, initlal.index, 1)) « 0; 
initlal.index :■ initlal.index + 1; 

ENDLOOP; 

rest.of.string SUBSTR (my.strlng, initlal.index + 1, 

my.string.length); 

CHANGE.CASE (initial.letter, UPPER); 

CHANGE.CASE (rest.of.string, LOWER); 
my.strlng :■ initial.letter * rest.of.string; 

MESSAGE (my.strlng); 

ENDPROCEDURE 
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TRANSLATE 


Invokes the Run-Time Library (RTL) procedure STR$TRANSLATE. 
The VAXTPU procedure takes three parameters. Some of the 
characters in the first parameter are replaced by the characters in 
the second parameter. The third parameter is used as a match 
string to determine which characters from the first parameter are 
replaced. For complete information on STR$TRANSLATE, see the 
appropriate volume of the VAX/VMS Run-Time Library Routines 
Reference Manual. 

FORMAT 

String 1 ) 

TRANSLATE (1 range \, string2, strings) 

. buffer ) 

parameters 

string 1 

One or more of the characters in this string are replaced by characters in the 
translate string (string2). 


range 

One or more of the characters in the range are replaced by characters in the 
translate string (string!). 


buffer 

One or more of the characters in the buffer are replaced by characters in the 
translate string (string!). 


string2 

The string containing the characters that are used to replace one or more 
characters in the first parameter. 


Strings 

The match string that determines how the replacement is done. The 
character(s) in the first parameter with the same index as character(s) in 
Strings are replaced by string!. 

DESCRIPTION 

If the translate string (string!) is shorter than the match string (stringS) and 
the matched character positions are greater than the character positions in the 
translate string, the translation character is a space. 


EXAMPLES 


□ TRANSLATE (8econd_buller, 'I'.'l') 

This command replaces all lowercase i's in the second buffer with 
uppercase I's. 
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Q SAMPLE PROCEDURE 

The following procedure translates the text you specify as "text—to—translate" 
according to the following pattern: any "A" is converted to an "N"; any “B" is 
converted to an "O'; and so on. 

! + 

I Procedure to translate characters to decipher acrambled text. 

I Characters are shifted 13 placet lor encryption. 

I- 

PROCEDURE user.trans.text ( text.to.translate ) 

TRANSLATE (text.to.translate, 

'NOPQRSTUVWXYZABCDEFGHIJKLMnopqrstuTwxyzabcdelghlj him', 
•ABCDEFGHIJKLMNOPQRSTUVWXYZabcdelghlJklmnopqrstuvKxyz'); 

ENDPROCEDURE 

g] SAMPLE PROCEDURE 


The following procedure strips the eighth bit from all characters in the current 
buffer. A procedure like this is useful for reading files from systems like 
TOPS-20 on which the eighth bit is set without using DEC Multinational 
Character Set. 

PROCEDURE user.strlp.elghth 
LOCAL 1, ! Loop counter 

seven, ! Ascii (0) through Ascii (127) 

eight; ! Ascii (128) through Ascii (265) 

! Build translate strings 
seven :« 
eight :« 

1 0 ; 

LOOP 

seven :> seven * ASCII (1); 
eight eight + ASCII (1 + 128); 

1 1 + 1 ; 

EXITIF 1 - 128; 

ENDLOOP; 

TRANSUTE (CURRENT.BUFFER, seven, eight); 

ENDPROCEDURE; 
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UNDEFINE_KEY 


Removes the current binding from the key that you specify. 


FORMAT UNDEFINE_KEY (keywordstring]) 


parameter keyword 

The name of a key or key combination that VAXTPU allows you to define. 
See Table 3-5 for a list of the valid VAXTPU keynames. 

String 

Specifies a key map or a key-map list in which the key is defined. The 
first definition of the key in the key maps that make up the key-map list is 
deleted. If neither a key map nor a key-map list is specified, the key-map list 
bound to the current buffer is used. 


DESCRIPTION After you use UNDEFINE _KEY, the key or key combination that you specify 

is no longer defined. VAXTPU does not save any previous definitions that 
you may have associated with the key. VAXTPU writes a message to the 
message buffer telling you that the key is undefined if you try to use it after 
you have undefined it. 


RETURN 

TPU$_NODEFINITION 



STATUS 

WARNING 

There is no definition for this key. 

TPU$_NOTDEFINABLE 

WARNING 

Second argument is not a valid 
reference to a key. 


TPU$_NOKEYMAP 

WARNING 

Fourth argument is not a defined key 
map. 


TPU$_NOKEYMAPLIST 

WARNING 

Fifth argument is not a defined key-map 
list. 


TPU$_KEYMAPNTFND 

WARNING 

The key map listed in the fourth 
argument is not found. 


TPU$_EMPTYKMLIST 

WARNING 

The key-map list specified in the fifth 
argument contains no key maps. 


EXAMPLES 

□ UNDEFINE_KET (CTRL.Z.KEY) 

This command removes the association between the key combination 
CTRL/Z and the code that it previously executed. 
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g SAMPLE PROCEDUKE 



The following procedure undefines a key. A procedure like this can be used 
by keypad initialization procedures. 

I 

! Parameters: 

! 

I whlcli_ksy Keyword for key to clear - input 
PROCEDURE user.elear.key (which_key) 

IF (L00KUP_KEY (which_key, PROGRAM) <> 0) 

THEN 

UNDEFINE_KEY (which.key); 

ELSE 

MESSAGE ('Key not defined”); 

ENDIF; 

ENDPROCEDURE 


g] SAMPLE PROCEDURE 



The following procedure deletes all of the key definitions in the key map 
TPU$KEY_MAP. 

PROCEDURE delete.all.deflnltions 
LOCAL key; 

key GET.INFO (DEFINED.KEY. "first", "tpu$key_map"); 

LOOP 

EXITIF key = 0; 

UNDEFINE_KEY (key, "tpulkey.map"); 

key := GET.INFO (DEFINED.KEY, "next", "tpulkey.map"); 

ENDLOOP; 

ENDPROCEDURE; 
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UNMAP 

Disassociates a window from its buffer and removes the window 
from the screen. 

FORMAT 

UNMAP (window) 

parameter 

window 

The window you want to remove from the screen. 

DESCRIPTION 

If you unmap the current window, VAXTPU tries to move the cursor position 
to another window that was most recently the current window. The window 
in which VAXTPU positions the cursor becomes the new current window, and 
the buffer that is associated with this window becomes the current buffer. 


The screen area of the window you unmap is either erased or returned to 
any windows that were occluded by the window you unmapped. VAXTPU 
returns lines to adjacent windows if the size of the windows requires the 
lines that were used for the window you UNMAP. The size of windows 
is determined by the values you specified for the built-in procedure 

CREATE—WINDOW when creating the window, or by the values you 
specified for the built-in procedure ADJUST-WINDOW if you changed 
the size of the window. If adjacent windows do not require the lines that 
were used by the window you UNMAP, the lines that the window occupied 
on the screen remain blank. 


The window that you unmap is not deleted from the list of available 
windows. You can cause the window to appear on the screen again with 
MAP. You do not have to create the window again. UNMAP does not have 
any effect on the existence of the buffer that was associated with the window 
that is being unmapped. 

RETURN 

STATUS 

TPU$_WINDNOTMAPPED WARNING Window is not mapped to a buffer. 

EXAMPLES 


Q UNHAP (maln.wlndow) 


This command removes the main window from the screen and disassociates 
the buffer that was mapped to the main window from it. 
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Q SAMPLE PROCEDURE 


The following procedure unmaps the current window and puts two new 
windows in its place. (Note that if the window that you are replacing has a 
status line, this line is not included in the screen area used by the two new 
windows. This is because GET_INFO (window, 'visible-bottom') does not 
take the status line into account.) 

PROCEDURE iwar_on«_wlndow_to_two 
LOCAL 

■Ind.laogth, 
wind Jialf, 
tlrst.llne, 
lut.linw; 

cor.wlnd :« CURRENT.WINDOW; 

! II it exiats 
IF (cur.wind <> 0) 

THEN 

lirat.Iina :• GET.INFO (cur.wind, 'viaibla.top'): 
laat.liaa ;> GET.INFO (cur.wind, 'viaibla.botton'): 
wind.bul ;■ GET.INFO (cur.wind, 'buffer'); 

UNNAP (cur.wind): 

ELSE 

! If there ia no currant window then create 
! an enpty buffer 
firat.lina :■ 1; 

laat.lina GET.INFO (SCREEN, 'viaibla.length'); 
wind.buf CREATE.BOFFER ('Empty Buffer'); 

ENDIF; 

wind.length (laat.line - firat.lina) 1; 
wind.half :> wind.length/2; 

naw.window.l CREATE.WINDOW (firat.lina, wind.half, OFF); 

SET (VIDEO, naw.window.l, UNDERLINE); 
new.window_2 :> CREATE.WINDOW (wlnd.balf+1, 

laat.llne-wlnd.half, OFF); 

! Aaaoclata the aame buffer with both windows 
! and nap the windowa to the screen 
MAP (naw.window.l, wlnd.buf); 

MAP (new.wlndow.2, wlnd.buf); 

ENDPROCEDURE 
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UPDATE 

Causes the screen manager to make a window reflect the current 
internal state of the buffer that is associated with the window. 

FORMAT 

UPDATE (window) 

parameter 

window 

The window that you want updated. The window must be mapped to the 
screen for the update to occur. 

DESCRIPTION 

The screen manager updates windows after each keystroke. This means that 
if a key is bound to a procedure, several built-in procedures may be executed 
before the screen actually reflects the internal state of the buffer. If you want 
the screen to reflect changes before the entire procedure is executed, you can 
force the immediate update of a window by adding an UPDATE statement to 
the procedure. 


UPDATE affects a single window that is visible on the screen. (However, if 
the buffer associated with the window you use as a parameter is associated ‘ 
with other windows that are mapped to the screen, all of these windows may 
be updated.) See REFRESH for a description of how to repaint every window 
on the screen. 

RETURN 

STATUS 

TPU$_WINDNOTMAPPED WARNING You cannot update a window that is 

not on the screen. 


EXAMPLES 


D UPDATE (new.wlndow) 

This command causes the screen manager to make new_window reflect the 
current internal state of the buffer associated with new_window. 

Q SAMPLE PROCEDURE 


The following procedure updates the screen to display the new line of text 
that you are inserting before the top line of the window. (When you insert 
text in front of the top of a window, the included text is not visible on the 
screen unless you use a procedure like the following to ensure that the text is 
displayed.) 
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PROCEDURE user.Bhow.flrst.line 
LOCAL 

! Marker of position before scroll 
old_posltlon, 

! Marker of position after scroll 
nsB.posltion; 

UPDATE (CURREMT.WINDOW): 

IF (GET.IHFO (CURREMT.WINDOW, "current.row") - 
GET.INFO (CURREMT.WINDOW, "vislble.top")) AND 
(CURRENT.COLUMN - 1) 

THEN 

old_position :> MARK (NONE); 

SCROLL (CURREMT.WINDOW, -1); 
nes.posltion :> MARK (NONE); 

! Make sure we scrolled before doing the cursor.vertical 
IF new.positlon <> old.poBltion 
THEN 

CURSOR.VERTICAL (1); 

ENDIF; 

ENDIF; 

ENDPROCEDURE 
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WRITE_FILE 


Writes data to the file that you specify. WRITE_FILE optionally 
returns a string that is the file specification of the file created. 


FORMAT 


|[string2 :=] WRITE_FILE 


A buffer 
\ range 


\l,string1]) 


parameters buffer 

The buffer whose contents you want to write to a file. 

range 

The range whose contents you want to write to a file. 

String 1 

A quoted string, a variable name representing a string constant, or an 
expression that evaluates to a string, that is the file specification to which 
data is written. If you do not specify a full file specification, VAXTPU writes 
the data to the current device and directory. 

This parameter is optional. If you omit it, VAXTPU uses the associated output 
file name for the buffer. If there is no associated file name, VAXTPU prompts 
you for one. If you do not give a file name at the prompt, VAXTPU does 
not write to a file. In that case, the optional string2 that is returned, is a null 
string. 


DESCRIPTION VAXTPU writes a message to the MESSAGE—BUFFER indicating how many 

records were written to an external file. 

If you specify a result, WRITE—FILE returns a string that is the file 
specification of the file to which the data was written. 

VAXTPU uses a flag to mark a buffer as modified or not modified. When you 
write data from a buffer to an external file, VAXTPU clears the modified flag 
for that buffer. If you do not make any further modifications to that buffer, 
VAXTPU does not consider the buffer as being modified and does not write 
out the file by default when you exit. 

See Appendix E for a list of the file types that VAXTPU supports. 


RETURN 

STATUS 


TPU$_CONTROLC ERROR The execution of the write operation 

terminated because you pressed 
CTRL/C. 
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EXAMPLES 

□ 1«IITE_FILE (paste.bufler, 'myfile.txt') 

This Statement writes the contents of the paste_bu£fer to the file named 
myfile.txt. 

Q uy_ill« :• WRITE.FILE (salact.rang*, 'oylile.txt') 

This assignment statement puts the file name to which the select—range is 
written in the string my—file. 

g] SAMPLE PROCEDURE 


The following procedure writes the contents of a buffer called extra_buf to a 
file (because you do not specify a file name, the associated file for the buffer 
is used). The procedure then removes the extra window and buffer from your 
editing context. 

PROCEDURE usar_write_lile 

WRITE.FILE (extra.bul); 

DELETE (axtra.window); 

DELETE (extra.bul); 

! Return the lines from extra_window to the main window 

ADJUST.WINDOW (maln.wlndow, -11, 0); 

ENDPROCEDURE 
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Previous sections have described the lexical elements of the VAXTPU 
language, such as data types, language statements, expressions, built-in 
procedures, and so on. This section describes how to combine these elements 
in VAXTPU programs. VAXTPU programs can be used to perform editing 
tasks, to customize or extend an existing interface, or to provide your own 
interface to VAXTPU. 

Before you start writing programs to customize or extend an existing interface, 
be very familiar with the VAXTPU source code that creates the interface that 
you want to change. If you want to change the size of a window that you 
use for editing, for example, you must know the variable name your interface 
uses for that window. 

If you use the EVE interface and you want to change the size of the main 
window, you must use the variable name eveSmairi—window. (Many of the 
EVE variables and procedure names begin with eve$.) See the appropriate 
chapter of the Guide to Text Processing on VAX/VMS for information on 
techniques for extending the EVE interface with VAXTPU. 

If you use the EDT Keypad Emulator interface and you want to change the 
size of the main window, you must use the variable name main—window. 
(Many of the EDT Keypad Emulator variables and procedure names begin 
with edt$; however, main—window does not use the prefix edt$.) See 
the appropriate chapter of the Guide to Text Processing on VAX/VMS for 
information on extending the EDT Keypad Emulator interface with VAXTPU. 

The sample procedures and syntax examples in this book use uppercase letters 
for items that you can enter exactly as shown. VAXTPU reserved words, such 
as built-in procedures, ke)rwords, and language statements are shown in 
uppercase. Lowercase items in a syntax example or sample procedure indicate 
that you must provide an appropriate substitute for that item. 

This section discusses the following topics: 

• Creating VAXTPU programs 

• Compiling VAXTPU programs 

• Executing VAXTPU programs 

• Debugging VAXTPU programs 

• Special VAXTPU programs (Initialization files) 

• Error handling 


5.1 Creating VAXTPU Programs 

Use an editing interface, such as EVE or the EDT Keypad Emulator, to enter 
or change the source code of a program in the VAXTPU language. A program 
can be a single executable statement or a collection of executable statements. 
These statements can be listed within PROCEDURE—ENDPROCEDURE 
statements, or they can be listed separately. 
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5.1.1 Simple Programs 

The following statement is an example of a simple program: 

SHOW (SUMMARY) 

The preceding statement, entered after the appropriate prompt from your 
editing interface, causes VAXTPU to execute the "program" associated with 
the SHOW (SUMMARY) statement. If you use the EOT Keypad Emulator 
interface with a user-written command file, your screen may display text 
similar to the following figure: 

Figure 5-1 SHOW (SUMMARY) Display 


TPU Version VI Update 2 

Journal file: WORK*:[USER]CHAP4.TJL;2 

Section file: SYSSCOMMON;[SYSLIB]EDTSECINI.TPUtSECTION;1 

Timer Message: Executing 

5 System buffers and 1 User buffer 

65 calls to LIBRGET.VM, 10 calls to LIBtFREE.VM, 983696 bytes still allocated 


5.1.2 Complex Programs 

The source code files that create the EVE interface and the EDT 
Keypad Emulator interface are examples of complex VAXTPU programs. 
EVESECINI.TPU and EDTSECINI.TPU contain many procedure definitions, 
and executable statements that specify what the screen layout and display 
is for the respective interfaces. These files also contain key definitions that 
specify which editing operations are performed when you press certain keys 
on the keyboard. You can examine the on-line copies of these files to study 
the VAXTPU code and notice the programming techniques that were used to 
create the two interfaces. The source code file that creates the EVE interface 
is SYS$LIBRARY:EVESEC1N1.TPU. The source code file that creates the EDT 
interface is SYS$L1BRARY:EDTSECIN1.TPU. See Section 5.5 for information 
on using command file or section files to create or customize an interface for 
VAXTPU. 


5.1.3 Program Syntax 

The syntax rules for writing VAXTPU programs are very simple. You must 
separate each executable statement from other statements with a semicolon. 
(Note that it is a statement separator, not a statement terminator.) In a 
program, you must position all procedure definitions before any executable 
statements that are not part of a procedure definition. (The rules for using 
the VAXTPU data types, language statements, and built-in procedures are 
discussed in previous sections.) Example 5-1 shows the correct syntax for a 
VAXTPU program. 

A variety of syntactically correct VAXTPU programs is shown in Example 5-2. 
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Example 5-1 Syntax of a VAXTPU Program 


PROCEDURE...ENDPROCEDURE 
PROCEDURE...ENDPROCEDURE 


PROCEDURE...ENDPROCEDURE 

stateaent-l: 

stat«meiit-3; 


■tatement-n; 


Example 5-2 Sample VAXTPU Programs 


IProgram 1 

IThla program consists of a single VAXTPU built-in procedure. 

SHOW (KEYWORDS) 

!Program 2 

IThis program consists of an assignment statement that 
I gives a value to the variable tpu$v_video. 

tputv.vldeo UNDERLINE; 

!Program 3 

!Thls program consists of the VAXTPU LOOP statement (with 
la condition for exiting) and the VAXTPU built-in procedure ERASE.LINE. 

X 0; LOOP x ;-x+l; EXITIF x > 100; ERASE.LINE; ENDLOOP 
{Program 4 

IThis program consists of a single procedure that causes VAXTPU 
Ito accept "(inl* as the command that signals a quit operation. 

PROCEDURE qul 

QUIT; I do VAXTPU quit operation 

ENDPROCEDURE 

{Program 5 

IThla program is a collection of procedures that 
{causes VAXTPU to accept "e", "ex”, or "exi" as 
{the command for a VAXTPU exit operation 
PROCEDURE a 

EXIT I do VAXTPU exit operation 

ENDPROCEDURE 

PROCEDURE ax 
EXIT 

ENDPROCEDURE 

PROCEDURE exl 
EXIT 

ENDPROCEDURE 


5.2 Compiling VAXTPU Programs 

Before compiling programs in VAXTPU, you should turn on informational 
messages to help you develop accurate programs. The EVE interface 
turns on the display of informational messages for you when you compile 
VAXTPU programs. If you use the EOT Keypad Emulator interface, enter the 
following command after the TPU Command: prompt to get informational 
level messages: 

SET (INFORMATIONAL, ON) 
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The line numbers that are mentioned in VAXTPU messages refer to line 
numbers in your source program. These numbers help you locate the line of 
your program at which an error is occmring. To move to the line at which 
the error occurred, position to the top of the buffer containing the program, 
and then enter the following VAXTPU command after the appropriate prompt 
from your interface: 

MOVE_VERTICAL («rror_line_nnBlMr -1) 

In EVE, instead of entering the preceding VAXTPU command, you could use 
the LINE command. For example, LINE 42, would move the current character 
position to line 42. 

If you use the EOT Keypad Emulator interface, the following suggestions 
will help you read VAXTPU messages that are several lines long and that 
scroll out of the message window before you can read them. Use the built-in 
procedure POSITION (message-window) to move to the message area. You 
can then use the arrow keys to scroll any messages that are off the screen 
back into the message window. 

Another way to read long messages is to enlarge the message window. The 
following command enlarges the EDT Keypad Emulator message window by 
adding two lines to the top of the window: 

ADJUST.WINDOW (nessage.window, -2, 0) 

In the EVE interface, use the command BUFFER MESSAGES to get to the 
message window. Use the command BUFFER name_of_buffer to return to 
the original buffer or another buffer of your choice. 

There are two ways to compile a program in VAXTPU: on the command line 
of EVE or the EDT Keypad Emulator, or in a VAXTPU buffer. 


5.2.1 Compiling on the Command Line of an Interface 

You can compile a simple VAXTPU program merely by entering it on the 
command line of your interface. Enter the command SHOW (SUMMARY) 
after the TPU Command: prompt and VAXTPU compiles (and executes) the 
program associated with the SHOW (SUMMARY) statement. 


5.2.2 Compiling in a VAXTPU Buffer 

VAXTPU programs are usually compiled by entering VAXTPU procedures 
and statements in a buffer and then compiling the buffer. Enter the statement 
SHOW (VARIABLES) in a buffer and then compile the buffer by entering the 
following statement after the appropriate prompt from your interface: 

COMPILE (CURREHT_BUFFER) 

The program associated with SHOW (VARIABLES) is not executed until you 
enter the following statement on the command line of your interface: 

EXECUTE (CURRENT_BUFFER) 

Note: You do not have to compile all programs before executing them. If 
you use a buffer, a range, or a string as the parameter for the built- 
in procedure EXECUTE, VAXTPU first compiles and then executes the 
preceding items. See the description of EXECUTE in Section 4. 
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The built-in procedure COMPILE optionally returns a program data type. If 
you want to use the program that you are compiling later in your session, you 
can assign the program that is returned to a variable name. The following 
example shows how to make this assignment: 

n«w.prograB COMPILE (CURRENT.BUFFER) 

If no error messages are issued while you compile the current buffer, you 
can then execute the program, new_program with the command EXECUTE 
(new_program). 

You can use the built-in procedure COMPILE to compile certain parts of a 
buffer rather than a whole buffer. Create a range that includes the statements 
within the buffer that you want compiled, and then specify the range as the 
parameter for COMPILE. 


5.3 Executing VAXTPU Programs 

You can use programs that are already compiled as parameters for the built-in 
procedure EJffiCUTE. In addition, you can use buffers, ranges, or strings 
that contain executable VAXTPU statements as parameters for the built-in 
procedure EXECUTE. VAXTPU first compiles the contents of the buffer, 
string, or range and then executes them. The following statement entered on 
the command line of your interface executes the program pointed to by the 
variable new—program that was compiled in the preceding section: 

EXECUTE (new.progreua) 

The following statement entered on the command line compiles and then 
executes the executable statements in the current buffer: 

EXECUTE (CUKR£NT_BUFFER) 

Small VAXTPU programs can be entered, compiled, and executed on the 
command lines of both EVE and the EDT Keypad Emulator. The following 
example shows a small program that you can enter after the prompt TPU 
Command:. 

SET (TIMER, ON, 'Executing') 

The preceding command executes the program associated with the VAXTPU 
built-in procedure SET (TIMER, ,,. ) and causes the string "Executing' to be 
displayed at one second intervals when a long procedure is executing. The 
string is displayed in the last 15 spaces of the prompt area at one second 
intervals. 


5.3.1 Interrupting Execution with CTRL/C 

Pressing CTRL/C causes VAXTPU to stop the execution of a user-written 
program. You can also stop the execution of the following VAXTPU built-in 
procedures with CTRL/C: 

• LEARN-BEGIN . .. LEARN_END (A learn sequence) 

• READ-FILE 
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• SEARCH 

• WRITE-JFILE 

Note: Because VAXTPU does not journal CTRL/C, using CTRL/C may affect 
the accuracy of your journal file. After using CTRL/C, DIGITAL suggests 
that you exit from the editor. This ensures that you do not lose any work 
because of an inaccrirate journal file. 


5.3.2 Procedure Execution 

If you include procedure definitions as part of a program, the procedure is 
compiled and the procedure name is added to VAXTPU list of procedures 
when you execute the program. Invoke the procedure in one of the following 
ways: 

1 Enter the name of the compiled procedure after the TPU Command: 
prompt from the EVE or the EDT Emulator Keypad interface. 

2 Call the procedure from within a program or another procedure. 


5.4 Debugging VAXTPU Programs 

VAXTPU allows you to write your own debugger to find out what is 
happening at critical points in your program. The points at which you 
stop execution of your program are called breakpoints. You can specify 
the breakpoints by using the appropriate parameters with the built-in 
procedure SET. See Section 4 for a description of the built-in procedure 
SET (DEBUG, . .. ). See the on-line copy of a sample user-written debugger, 
SYS$LIBRARY;DEBUG.TPU. 

The following steps show how you might use a debugger with VAXTPU: 

1 Write a VAXTPU program like SYS$LIBRARY:DEBUG.TPU that handles 
debugging. 

2 Write a procedure or program in VAXTPU that you want to debug. 

3 Use an editing interface that provides two text buffers. Read the VAXTPU 
program you want to debug into one buffer, and the debugger program 
into the other buffer. 

4 Compile the buffer that contains the program that you want to debug, and 
then compile the buffer that contains the debugger program. 

5 On the command line of your interface, use the built-in procedure SET 
(DEBUG, ... ) to specify any of the following: 

• The procedure or program that you want to debug 

• Whether you want single step debugging 

• The name of the program you want to use as a debugger 

To specify the program you want to use as a debugger, for example, enter 
the following command: 

SET (DEBUG, PROGRAM, 'your.debugger.prograa') 
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6 Your debugger program should provide a prompt like DEBUG> and 
debugger commands. Enter the appropriate commands after the prompt. 

7 Use the debugger to step through your program to find problems. 

8 Exit from the debugger. 


5.5 Special VAXTPU Programs (Initialization Files) 

There are two types of VAXTPU initialization files: 

• Command Files 

• Section Files 

A command file is a VAXTPU source code file that is specified after the 
qualifier /COMMAND when invoking VAXTPU. A section file is the 
compiled, binary form of a VAXTPU source code file that is specified after the 
qualifier /SECTION when invoking VAXTPU. 

DIGITAL suggests that you do minor customizing of an editing interface with 
a command file. If the command file gets large, or if you want to make major 
changes or additions to an interface, it is more efficient to use a binary section 
file when invoking VAXTPU. The following sections describe how to write 
and use VAXTPU command files and VAXTPU section files. 


5.5.1 Command Files 


A command file is a VAXTPU source code file that can contain procedures, 
key definitions, and other VAXTPU executable statements. You can have 
any number of command files in your directory. You might want to write 
one conunand file that customizes your editor for programnung in PASCAL, 
another command file that customizes your editor for text editing, and so on. 
If you have several command files, give them names that remind you of their 
contents. If you have one command file that you use most of the time, name 
it TPUINI.TPU. 

The syntax to invoke VAXTPU command files at the DCL command level is 
as follows: 

t EDIT/TPU/COMHAND [[- llls-speci 

If you name your command file TPUINI.TPU and it is in your current 
directory, VAXTPU reads the file by default. If you name your file something 
other than TPUINI.TPU, or if you put it in a directory other than yotur current 
directory, you have to explicitly use the qualifier /COMMAND and provide a 
full file specification after the qualifier. 

VAXTPU reads a command file, compiles it, and executes any commands that 
do not contain syntax errors. If there are errors, VAXTPU writes an error 
message to the message area. The procedures and key definitions in the 
command file can modify the interface that is defined in the section file with 
which you invoked VAXTPU. 

To write a command file, follow the VAXTPU programming conventions 
discussed throughout this manual. A command file should not contain the 
built-in procedure SAVE. SAVE is used when you want to create or add to a 
section ffie. 
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Example 5-3 is a sample VAXTPU command file that modifies the default 
screen layout of the EDT Keypad Emulator interface by creating a second 
window that you can use for editing. 

Example 5-3 Command File for Two Windows 


PROCEDURE two_fll«s 

«xtra_lil« READ.LINE ('File name: "); I aak lor file name 
extra_bul :• CREATE_BUFFER ("EXTRA", extra_file); 
extra_window ;= CREATE.WINDOW (1, 11, ON); 

ADJUST.WINDOW (main_wlndoa, -•-ll, 0); ! Reduce the main window 

SET(STATUS_LINE, extra_window, REVERSE, 

"EXTRA WINDOW / EXTRA BUFFER"); 

MAP (extra_window, extra_buf); 

ENDPROCEDURE 


If you name the file that contains this procedure two_wind.TPU, you can 
invoke VAXTPU with the EDT Keypad Emulator and your command file in 
the following way; 

$ EDIT/TPU/SECTION*EDTSECINI/COMMAND»device:[user]two.wind.TPU 

If you add procedures or statements to the command file two_wind.tpu, place 
all procedures before any individual statements that are not listed within a 
procedure (for example, key definitions to move the cursor from one window 
to another.) 

Remember to name your variables and procedures so they do not conflict 
with VAXTPU reserved words and predefined identifiers. You can prefix your 
variable and procedure names with three letters (your initials, for example) 
followed by an underscore (_). You can name the preceding procedure 
xyz—two—windows, for example. 


5.5.2 Section Files 


A section file is a binary representation of a VAXTPU editing environment. It 
is a collection of compiled VAXTPU procedure definitions, variable definitions, 
and key bindings. The advantage to using a binary file to define your 
interface is that the source code does not have to be compiled each time 
the editor is invoked, and therefore, your VAXTPU interface starts up quickly. 


5.5.2.1 Writing a Section File 

To create a section file, begin by writing a program in the VAXTPU language. 
The program must adhere to all the programming conventions discussed 
throughout this document. These include the use of PROCEDURE and 
ENDPROCEDURE statements to create named procedures that can be called 
during program execution. Procedure definitions must come before any 
individual executable statements in your program. 

Depending upon the kind of section file you create, the program should 
include one of the following initialization procedures: 

• TPU$INIT_PROCEDURE 

• TPU$LOCAL_INIT 
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If you create a new section file rather than add to an existing editing 
interface, your program should include TPU$INIT_PROCEDURE. 
TPU$INIT_PROCEDURE contains statements that create buffers, create 
windows, associate windows to buffers, set up screen attributes, initialize 
variables, define how the journal facility works, and so on. The location 
of TPUSINIT-PROCEDURE in a program is not critical to its function 
within the program. Both EVE and the EDT Keypad Emulator have a 
TPU$INIT_PROCEDURE in their code. See Section 5.5.2.3 for more 
information on TPU$INIT_JPROCEDURE. 

If you create a section file by adding elements to an existing section file, 
put your initialization items in TPU$LOCAL_INIT. Both EVE and the EDT 
Keypad Emulator have an empty procedure named TPU$LOCAL_INIT 
that is called at the end of TPU$INIT_PROCEDURE. Your procedure 
named TPU$LOCAL_INIT supersedes the original, empty value of 
TPU$LOCAL_INIT in your interface. Use TPU$LOCAL_JNIT to add your 
own initialization items to those provided by your interface. 

The final line of a program used to create a section file should be the QUIT 
statement. QUIT causes you to leave the editor, preventing any further 
editing. Immediately preceding the QUIT statement, there should be a line 
containing the built-in procedure SAVE. SAVE is the mechanism by which 
you store all currently defined procedures, variable names, and bound keys in 
binary form. If you need more information on the built-in procedure SAVE, 
see Section 4. 

Following is a summary of the basic components of a VAXTPU source 
program from which a section file can be created: 

• A procedure called TPU$INIT_PROCEDURE or TPU$LOCAL_INIT. 

• Procedures delimited by PROCEDURE and ENDPROCEDURE statements. 

• Executable VAXTPU statements (following any procedure definitions). 

• The built-in procedure SAVE ("file-spec") as the next to last line in the 
program. 

• The built-in procedure QUIT as the last line in the program. 

Example 5-4 shows the syntax of a program that could be used to create a 
section file: 

Example 5-4 Sample Program for a Section File 


PROCEDURE tpntloc«l.iait 


ENDPROCEDURE; 
PROCEDURE TtlOO.keys; 


ENDPROCEDURE: 

TtlOO.kayi; ICall the procedure that defines the keys 
SAVE (•sy#$login:vtlOOini.TPU$SECTION"); 

QUIT; 
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5.5.2.2 Processing a Section Fiie 

There are two ways to process a section file. If you are adding items to an 
existing section file, invoke VAXTPU with a section file and a command file, 
and then SAVE the combined section file (this is called an incremental SAVE). 
If you are creating a new section file, invoke VAXTPU with a command file, 
but without a section file, and then SAVE the new section file. The steps for 
doing these two types of processing are described in the following sections. 

To add to an existing section file, follow these steps; 

1 Invoke VAXTPU with an existing section file such as EVE or the EDT 
Keypad Emulator and a user-written command file: 

» EDIT/TPU/SECTION-EVESECINI/COMMAND-ay.edltor.TPU 

The preceding command causes VAXTPU to read the section file and 
then read, compile, and execute the command file you specify. The user- 
written command file should have a procedure called TPU$LOCAL _INIT 
that contains initialization items. The combined editing context of the 
section file and the command file is now available for you to use. 

2 Save the combined editing context for future sessions with one of the 
following methods; 

— Execute the built-in procedure SAVE on the command line of the 
interface you created and specify the file in which you want to save the 
interface, as the parameter for SAVE. Then enter the built-in procedure 
QUIT on the command line. 

— Include the built-in procedures SAVE and QUIT as the last two lines in 
your command file. When you invoke VAXTPU, the combined section 
file is created, and the program leaves the editor. You can then invoke 
the editor with the new section file. 

Note: You can modify an existing section file by making changes to the source 
code file that creates the section file, and then recompiling the section file. 
However, DIGITAL does not recommend doing this, because it may cause 
problems when a new version of VAXTPU is released. It is easier for you 
to establish your editing environment on a new version of VAXTPU if 
you have a command file that you can use to do an incremental save on 
any new interfaces. 

To create a new section file, follow these steps: 

1 Invoke VAXTPU without a section file, but specify a user-written 
command file: 

$ EDIT/TPU/NOSECTION/COMMAND-By.»<litor. TPU 

The preceding command causes VAXTPU to read, compile, and execute 
items in the command file my_editor.TPU. The command file should have 
a procedure called TPU$INIT_PROCEDURE that contains initialization 
items. 

2 Save the editing context established by the command file with one of the 
following methods: 

— Execute the built-in procedure SAVE on the command line of your 
interface and specify the file in which you want to save the editing 
environment as the parameter for SAVE. Then enter the built-in 
procedure QUIT on the command line. 
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— Include the built-in procedures SAVE and QUIT as the last two lines in 
your command file. When you invoke VAXTPU, the new section file 
is created, and the program leaves the editor. You can then invoke the 
editor with the new section file. 


5.5.2.3 A Sample Section File 

If you choose to design an interface for VAXTPU that is entirely separate from 
the EVE and the EOT Keypad Emulator interfaces, you must provide certain 
basic structures and key definitions to be able to use the VAXTPU compiler 
and interpreter. Example 5-5 is a sample of the source code that creates a 
minimal interface. It provides the following basic structures: 

• A buffer and a window for VAXTPU messages 

• A buffer and a window for information from the built-in procedure SHOW 

• A buffer and a window in which to enter VAXTPU programs or text 

• A prompt area in which to enter VAXTPU commands 

Because VAXTPU, when invoked without a section file, does not have any 
keys defined, the sample program also contains the following key definitions: 

• The RETURN key 

• The DELETE key 

• Key definition for exiting from VAXTPU 

• Key definition for entering VAXTPU commands—this program uses the 

TAB key. 

By default, VAXTPU looks for TPU$INIT_PROCEDURE, so the statements 
that create the structures for a minimal interface are contained in 
TPU$INIT_PROCEDURE. Individual statements that define keys come after 
any procedures in the file. 

To process the source code file in Example 5-5, enter the following command 
at the DCL level: 

$ EDIT/TPU/NOSECTION/COMMAND-nini.TPU 

When you enter this command, the qualifier /NOSECTION specifies that 
no section file is to be read. (This ensures that none of the procedures 
or variables from an existing section file are loaded into the internal 
VAXTPU tables.) The quali&r /COMMAND specifies that the command 
file, mini.TPU, is to be compiled by VAXTPU. The built-in procedure SAVE 
at the end of the command file specifies that all of the procedures, variables, 
and key definitions in the file are to be saved in binary form in the file 
sys$login:mini.TPU$SECTION. The built-in procedure QUIT then causes you 
to leave VAXTPU. 

The procedures and definitions from your section file are used as your 
interface to VAXTPU when you now invoke VAXTPU with the following 
command: 

$ EDIT/TPU/SECTION-sys$login;mini your.text.fil 

Rather than entering this long command each time you invoke VAXTPU, 
define the logical name TPUSECINI to point to your section file. By default, 
VAXTPU looks for a file that TPUSECINI points to, and reads that file as the 
default section file. 
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Example 5-5 Source Code for Minimal Interface 


! mlni.TPU - minimal VAXTPU interface 
PROCEDURE tpulinlt.procedure 
! Create a buffer and window for messages 

message.buffer ;» CREATE.BUFFER ("Message Buffer"); 

SET (NO.WRITE, message.buffer); 

SET (SYSTEM, message.buffer); 

SET (EOB.TEXT, message.buffer, "); 
message.window CREATE.WINDOW (21, 4, OFF); 

MAP (message.window, message.buffer); 

! Create a buffer and window for SHOW 

show.buffer := CREATE.BUFFER("Show Buffer"); 

SET (NO.WRITE, show.buffer); 

SET (SYSTEM, show.buffer); 

info.window := CREATE.WINDOW (1, 20, ON); 

! Create a buffer and window for editing 

main.buffer := CREATE.BUFFER ("Main Buffer"); 
main.window ;= CREATE.WINDOW (1, 20, ON); 

MAP (maln_wlndow, main.buffer); 

! Create an area on the screen for prompts 
SET (PROMPT.AREA, 21, 1, NONE); 

!Put the current character position in the main buffer 
POSITION (main.buffer); 

ENDPROCEDURE; 

! Define the minimal editing keys: 

DEFINE.KEY ("SPLIT.LINE", RET.KEY); 

DEFINE.KEY ("ERASE.CHARACTER(-l)", DEL.KEY); 

DEFINE.KEY ("EXECUTE(READ.LINE('TPU command: '))", TAB.KEY); 
DEFINE.KEY ("EXIT", CTRL.Z.KEY); 

! Create a section file and then quit 
SAVE ("sys$login:mini.TPOSSECTION”); 

QUIT; 

!End of mlni.TPU 


Whenever you want to add new procedures, variables, learn sequences, or 
key definitions to a section file, edit the command file to include the new 
items, and then recompile the command file to produce a section file with the 
new items. For example, if you wanted to add key definitions for the arrow 
keys, you could edit the file mini.TPU and add the following statements (put 
them after any procedures in the file): 

DEFINE.KEY ("MOVE.VEBTICAL(-l)", DP); 

DEFINE.KEY ("MOVE.VERTICAL(l)", DOWN); 

DEFINE.KEY ("MOVE.HORIZONTAL(1)", RIGHT); 

DEFINE.KEY ("MOVE.HORIZONTAL(-l)", LEFT); 

Then recompile the command file with the following command: 

9 EDIT/TPU/NOSECTION/COMMAND=mini.TPU 

Now, when you invoke VAXTPU with the section file mini.TPU$SECT10N, 
the new key definitions are included. 

An alternate way of adding these key definitions to your section file is to 
enter the definitions as text in the current buffer. You could then press the 
TAB key (the command prompt for the minimal interface) and enter the 
following command after the prompt: 

EXECUTE (CURRENT.BUFFER) 
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This causes the new key definitions to be added to your current editing 
context. To cause the definitions to be added to the section file so that you 
can use them in future sessions, enter the following statement after the 
command prompt: 

SAVE (“syBlloginimini.TPUSSECTION") 

If you want to save the VAXTPU source code for the key definitions, write out 
the current buffer or use the built-in procedure EXIT to leave the VAXTPU 
session so that the contents of the buffer are written to a file. 


5.5.2.4 Special Items for Section Files 

The following items should be included in a section file. If you use one of 
the editing interfaces provided by VAXTPU, the section file that creates the 
interface provides these structures and procedures. If you choose to write 
your own interface without using an existing interface, you must provide 
these structures and procedures. 

A section file should include a procedure called TPU$INIT_PROCEDURE 
and should recognize the special identifiers MESSAGE-BUFFER, 
SHOW-BUFFER, and INFO—WINDOW. These special items are described in 
the following sections. 


5.5.2.4.1 TPU$INIT-PROCEDURE 

This procedure should perform the following operations: 

• Initialize all global variables to their original value. 

• Create all required work spaces for the editor (see the list of special 
purpose buffers and windows in the following section). 

You can add other functions to TPU$INIT—PROCEDURE, but it should 
perform at least these two operations. 


5.5.2.4.2 Special Identifiers 

The VAXTPU editing language attaches a special meaning to the following 
identifiers: 

• Identifier for Message Information 

— MESSAGE—BUFFER—VAXTPU stores messages received from built-in 
procedures in this buffer. 

If the MESSAGE—BUFFER is associated with a window that is mapped 
to the screen, VAXTPU updates the window. 

• Identifiers for SHOW Information 

—■ SHOW—BUFFER—VAXTPU stores information from the built-in 
procedure SHOW in this buffer. 

— INFO—WINDOW—VAXTPU displays messages stored in the 
SHOW—BUFFER and information from the built-in procedure 
HELP—TEXT in this screen region, if it exists. 

If you want to use the built-in procedure SHOW, you must create these 
special identifiers that VAXTPU uses for SHOW. 
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5.6 Error Handling 

VAXTPU built-in procedures can return SUCCESS, INFORMATIONAL, 
WARNING, ERROR, or FATAL status. You can gain control of the messages 
generated by these return statuses in one of the following ways: 

1 Use an ON—ERROR language statement at the beginning of a procedure 
to trap WARNING or E^OR messages returned by built-in procedures 
executed within that particular procedure. 

2 Use SET (INFORMATIONAL, OFF) or SET (SUCCESS, OFF) to suppress 
the display of INFORMATIONAL or SUCCESS messages. 

In addition to messages that are generated by VAXTPU, a built-in procedure 
may return system messages. Appendix C contains an alphabetized list of 
all the possible return statuses for VAXTPU and their severity levels. The 
VAX/VMS System Messages and Recovery Procedures Reference Manual includes 
all the possible return statuses for VAXTPU as well as the appropriate 
explanations and suggested user actions. In addition, each built-in procedure 
that can return a WARNING or ERROR message has the possible message 
it can return listed in a section called RETURN STATUS in the individual 
built-in procedure description. 

All built-in procedures can return the following messages: 

• TPU$—SUCCESS (SUCCESS)—The built-in executed successfully. 

• TPU$_ARGMISMATCH (ERROR)—Data type of argument is not 
supported by built-in that is being called. 

• TPU$_TOOFEW (ERROR)—Not enough arguments were passed in the 
built-in call. 

• TPU$_TOOMANY (ERROR)—Too many arguments were passed in the 
built-in call. 

See Section 3.8.1.6 for a description of how to use the ON_ERROR language 
statement to trap ERROR and WARNING messages. 
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Overview 


When you enter the following command at the DIGITAL Command Language 
(DCL) level, you invoke VAXTPU and a binary section file that creates the 
EVE editing interface: 

I EDIT/TPU 

VAXTPU provides two section files: 

• SYS$UBRARY:EVESECINI.TPU$SECTION (for the EVE interface) 

• SYS$UBRARY:EDTSECINLTPU$SECTION (for the VAXTPU EDT Keypad 
Emulator) 

If you want to use the EDT Keypad Emulator interface with VAXTPU, you 
can define the logical name TPUSECINI to point to the EDT Ke)rpad Emulator 
section file as follows: 

$ DEFINE TPUSECINI EDTSECINI 

Otherwise, you can enter the following command at the DCL level: 

$ edit/tpo/section-edtsecini 

The qualifier /SECTION is described along with the other EDIT/TPU 
command qualifiers in Section 6.4. 

In addition to specifying qualifiers for the EDIT/TPU command, you can 
specify parameters at the DCL level. The parameters that you can use after 
EDIT/TPU are described in Section 6.5. 

Besides invoking VAXTPU at the DCL level for interactive editing, you can 
invoke VAXTPU from a the DCL command procedure and you can run 
VAXTPU in a batch job. These alternative ways of invoking VAXTPU are 
explained in the following sections. 


Invoking VAXTPU from a DCL Command Procedure 

There are two main reasons that you might want to invoke VAXTPU from a 
command procedure: 

• To set up a special environment for interactive editing 

• To set up a batch-like job 

(The edits themselves are not visible on the screen, but the results of the 
editing session are sent to the terminal.) 
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6.2.1 Setting Up a Special Editing Environment 

You can run VAXTPU with a special editing environment by writing a DCL 
command procedure that first establishes the environment that you want, and 
then invokes VAXTPU. You must assign SYS$COMMAND to be the same 
value as SYS$INPUT. 

Example 6-1 shows a DCL command procedure that 'remembers" the last file 
that you were editing and uses it as the input file for VAXTPU. After making 
file name assignments, this DCL command procedure invokes VAXTPU with 
the default section file (because you do not specify a different section file) and 
with a user-written command file. 

Example 6-1 DCL Command Procedure filename.COM 


$ SET NOVERIFY 

$ ASSIGN/USER SYSSCOMMAND SYSlINPUT 
$ IF PI .NES. "" THEN F_ 'PI 
$ VmiTE SYSSOUTPUT "*•* '>F_' *•*" 

$ EDIT/TPU/COMMAND-DISKI:[USER]TPUINI.TPU 'F_ 


Example 6-2 establishes an environment that specifies tab stop settings for 
FORTRAN programs. 

Example 6-2 DCL Command Procedure fortran_ts.COM 


$ SET NOVEEIFY 

$ ASSIGN/USER SYStCOMMAND SYStINPUT 
$ IF PI .EQS. ” THEN GOTO REGULAR.INVOKE 
$ F_ ;=» 'PI 

$ FTN.TEST « F$FILE_ATTRIBOTES {F_."RAT") 

$ IF FTN.TEST .NES. "FTN*' THEN GOTO REGULAR.INVOKE 
$ FTN.INVOKE: 

$ EDIT/TPO/SECTION-EVESECINI/COMMAND-FTNTABS.TPU 'F_ 

$ GOTO TPU_DONE 
$ REGULAR_INVOKE: 

$ EDIT/TPU/SECTION-EVESECINI 'F. 

$ TPU_DONE: 

- W 


6.2.2 Setting Up Batch-Like Editing 


In some situations, you may want to put all of your editing commands in 
a file and have them read from the file rather than entering the commands 
interactively. You may also want VAXTPU to perform the edits without 
displaying them on the screen. You can do this type of editing from a batch 
job, or if you want to see the results of the editing session displayed on your 
screen, you can do this type of editing from a DCL command procedure. 
Even though the edits are not displayed on your screen as they are being 
made, your terminal is not free while the command procedure is executing. 
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Example 6-3 shows a DCL command procedure named invisible_tpu.COM 
that contains a single command line that invokes VAXTPU in the following 
way: 

• /NOSECTION—No section file (no procedures or key definitions are used 
from a binary section file to initialize the editor). 

• /COMMAND = gsr.TPU—A command file containing the edits to be 
made. 

• /NODISPLAY—No screen management features (windows, cursor, and so 
on) are recognized. 

Example 6-3 DCL Command Procedure invisible—tpu.COM 


! This command procedure invokes VAXTPU without an editing Interlace 
! The lile gsr.TPU contains the edits to be made 
! Specify the lile you want the edits made to as pi 
! 

$ EDIT/TPU/NOSECTION/COHMAND>gsr.TPU/NODISPUY 'pi' 

I 


The file gsr.TPU, which is used as the file specification for the qualifier 
/COMMAND, performs a search through the current buffer and replaces a 
string or a pattern with a string. Example 6-4 shows the file gsr.TPU. 

Example 6-4 VAXTPU Command File gsr.TPU 


PROCEDURE global_search_rsplace (str.or.pat, str2) 

! This procedure performs a search through the current 
! buffer and replaces a string or a pattern with a new string 
LOCAL src_range, replacement .count; 

! Return to caller if string not found 
ON_ERROR 

msg_tert :• FAO ('Completed !UL replacement!XS', replacement.count); 
MESSAGE (asg_text): 

RETURN; 

ENDON_ERROR; 
replacement.count := 0; 

LOOP 

src.range :■ SEARCH (str.or.pat, FORWARD); 

ERASE (src.range); 

POSITION (END.OF (src.range)); 

COPY.TEXT (str2); 

replacement.count :• replacement.count * 1; 

ENDLOOP; 

ENDPROCEDURE I global.search.replaee 

! Executable statements 

lnput.file :« GET.INFO (COMMAND.LINE, 'file.name'); 
maln.buffer:> CREATE.BUFFER ('main', lnput.file); 

POSITION (BEGINNING.OF (maln.buffer)); 
global.search.replaee ('xyzl.', 'usert.'); 
patl;« " k LINE.BEGIN t 't'; 

POSITION (BEGINNING.OF (maln.buffer)); 
global.search.replaee (patl, 'T'); 

WRITE.FILE (nain.buffer, 'newflle.dat'); 

QUIT; 


! Search returns a range if found 
! Remove first string 
I Move to right place 
I Replace with second string 


To process these files interactively, enter the following command: 

$ Clnvisible.tpu flle-to-edit 
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Note: If you specify /NODISPLAY after the EDIT/TPU command, do not define 
any keys, or create or manipulate any windows in the file that contains 
your e^ts. 

If you leave the editor with the built-in procedures QUIT or EXIT, 
you must explicitly write out any modified buffers. (This is shown in 
Example 6-4.) If you modify butters and do not write them out, you can 
go into an infinite loop. VAXTPU does not complete a QUIT or EXIT 
command if there are any modified butters that have not been written 
out to disk. Instead, VAXTPU prompts you so that you are aware that 
the contents of modified butters are lost if you do not write them. If you 
run in /NODISPLAY mode, you do not see the VAXTPU prompt, and 
VAXTPU loops while waiting for an answer to the prompt. 


6.3 Invoking VAXTPU from a Batch Job 

If you want your edits to be made in batch rather than at the terminal, you 
can use the DCL command SUBMIT to send your job to a batch queue. 

For example, if you want to make the edits from the file gsr.TPU (shown in 
Example 6-4) in batch mode, enter the following command: 

$ SUBMIT iiivlslbl«_tpu.C0H/L0G*invi8lbl«_tpu.LOG/paran«ter*lile-to-«dit 

This job is then entered on the default batch queue for your system. The 
results are sent to the LOG file that the batch job creates. 

The restrictions that apply to the batch-like command procedure also apply to 
a batch job. See the NOTE in the previous section, for information on using 
the qualifier /NODISPLAY, and the built-in procedures EXIT or QUIT in the 
file that contains your edits. 


6.4 EDIT/TPU Command Qualifiers 

You can use qualifiers with the command EDIT/TPU to specify special kinds 
of processing. The following table lists the qualifiers and the qualifier defaults 
for the command EDIT/TPU: 


QUALIFIER 

DEFAULT 

/[NO]|COMMANDHile-spec] 

/COMMAND=TPUINI 

/INOJCREATE 

/CREATE 

/|[NO]DISPLAYI=file-specI 

/DISPLAY-TPUSCCTSHR 

/IIN01J0URNAL|=file-specI 

/JOURNALHnput-file.TJL 

/IN0]10UTPUTI=file-specl 

/OUTPUT“input-file .type 

/|[NO]READ_ONLY 

/NOREAD-ONLY 

/[NOIRECOVER 

/NORECOVER 

/l[N01SECTI0NI=file-specl 

/SECTION=TPUSECINI 


The following sections describe each of the qualifiers. The examples in the 
following sections show the qualifiers typed directly after the EDIT/TPU 
command and before the input file specification. You can place the qualifiers 
anywhere on the VAX/VMS command line after the command EDIT/TPU. 
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r> 


r> 


6.4.1 /COMMAND 

/COMMAND=TPUINI.TPU (D) 

/NOCOMMAND 

Determines whether VAXTPU reads a user-written command file for 
initialization purposes. The default file type for VAXTPU command files 
is TPU. By defaiUt, VAXTPU tries to read a command file called TPUINI.TPU 
in yoiu: default directory. You can use a full file specification after the qualifier 
/COMMAND or define the logical name TPUINl to point to a command file 
other than the default one. 

The following command causes VAXTPU to read a command file named 
sys$login:my_tpuini.TPU and uses letter.mo as the input file for an editing 
session: 

$ EDIT/TPU/COHHAtn}>Bys$logiii;Dy_tpulDl.TPU letter.mo 

To prevent VAXTPU from processing a command file, use the qualifier 
/NOCOMMAND. If you generally invoke VAXTPU without a command file, 
define a symbol similar to the following: 

$ EVE — "EDIT/TPU/NOCOMMAND" 

Using /NOCOMMAND when you do not want to use a command file 
decreases startup time by eliminating the search for a command file. 


6.4.2 /CREATE 

/CREATE(D) 

/NOCREATE 

Determines whether VAXTPU creates a new file when the specified input 
file does not exist. The interface that is layered on VAXTPU is responsible 
for processing this qualifier. The interface can get information on whether 
the qualifier was specified when VAXTPU was invoked by using the built-in 
procedure GET_INFO, for example, x := GET_INFO (COMMAND-LINE, 
'create'). For information on GET-JNFO, see Section 4. 

By default, the VAXTPU editing interfaces provide a buffer in which to create 
the file. If you write out the contents of the buffer (either with the built-in 
procedure WRITE—FILE procedure or by exiting from the editor), VAXTPU 
creates a new file for the input file specification. 

If you use /NOCREATE when invoking VAXTPU, and if you specify an input 
file that does not exist, the VAXTPU interfaces print an error message and 
return you to the DCL command level as follows: 

I EDIT/TPU/NOCREATE n«wlil«.dat 

Input file does not exist: DISKI:[USERDNEWFILE.DAT; 

I 
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6.4.3 /DISPLAY 

/DISPLAY[“screen_management_filename| (D) 

/NODISPLAY 

Determines whether a VAXTPU session is run from a supported terminal 
and whether the session uses terminal functions such as the screen display 
and the keyboard. By default your VAXTPU session is run with the screen 
management file, SYS$SHARE:TPU$CCTSHR.EXE, for terminals that respond 
to ANSI control functions and that operate in ANSI mode. 

VAXTPU expects sessions to be run from a supported terminal unless 
you specify /NODISPLAY. If an unsupported input device is used when 
/DISPLAY is active, VAXTPU returns an error message and the session is 
terminated. (See Appendix B for information on terminals supported by 
VAXTPU.) 

The qualifier /NODISPLAY causes VAXTPU to run without using the 
screen display and the keyboard functions of a terminal. Use the qualifier 
/NODISPLAY in the following cases: 

• When running VAXTPU procedures in a batch job 

• When using VAXTPU on an unsupported terminal 

If you use /NODISPLAY, VAXTPU window or screen manipulation 
commands and key definitions cause errors. Initialization files that contain 
screen manipulation commands (ADJUST-WINDOW, CREATE—WINDOW, 
MAP) and key definitions can run when the /NODISPLAY feature is 
active. However, the commands are meaningless and may even return error 
messages in the batch log file or on your screen. Use a special initialization 
file (either a section file or a command file) for sessions in which you use 
the qualifier /NODISPLAY. This file should not include key definitions or 
screen manipulation commands (except for READ—LINE, MESSAGE, and 
LAST—KEY, which work with some restrictions). See the descriptions of 
READ—LINE and LAST—KEY in Section 4 for a list of the restrictions. The 
file should be a complete VAXTPU session; it should end with either the 
command EXIT or the command QUIT. 

The following command causes VAXTPU to edit the file my—batch—file.mo 
without using terminal functions such as screen display: 

t EDIT/TPU/NODISPUY my.batch.fil«. rno 


6.4.4 /JOURNAL 

/JOURNAL=input-file.TJL (D) 

/NOJOURNAL 

Determines whether VAXTPU keeps a journal file of your editing session 
so that you can recover from an interrupted session. The interface that is 
layered on VAXTPU is responsible for processing this qualifier. The interface 
can get information on whether the qualifier was specified when VAXTPU 
was invoked by using the built-in procedure GET—INFO, for example, x := 
GET_JNFO (COMMAND-LINE, 'journal'). For information on GET-INFO, 
see Section 4. 
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By default the VAXTPU interfaces maintain a journal file that has the same 
name as the input file and the file type TJL. If you invoke VAXTPU without 
a file specification, the default name for the journal file is TPU.TJL. Use a full 
file specification with the qualifier /JOURNAL to specify a different name for 
the journal file. 

If you edit a file from another directory and you want the journal file to 
be located in that directory, you must use the qualifier /JOURNAL with a 
file specification that includes the directory name. Otherivise, the VAXTPU 
interfaces create the journal file in the default directory. 

The built-in procedure JOURNAL—OPEN also controls whether VAXTPU 
CTeates a journal file for the editing session and, if so, what name it uses. 

In the EOT Keypad Emulator and EVE initialization files, the qualifier 
/JOURNAL, used when invoking VAXTPU, overrides the file name and file 
extension that is given to the journal file by the JOURNAL—OPEN command. 
These interfaces turn journaling on automatically if you do not explicitly use 
/NOJOURNAL. Using /NOJOURNAL in one of these environments prevents 
the execution of the JOURNAL—OPEN command. 

VAXTPU provides a 500-byte buffer for journaling keystrokes. If journaling is 
enabled, a write to the journal file occurs when the buffer is full. You can use 
the built-in procedure SET (JOURNALING, integer) to adjust the journaling 
frequency to your specifications. The integer can range from 1 to 10. The 
default, which is 10, causes a write to the buffer every 500 bytes. A lower 
integer causes a write to the buffer more frequently. Note, however, that 
lowering the integer causes a slight decrease in VAXTPU's performance. 

Once you create a journal file, use the qualifier /RECOVER to have VAXTPU 
process the commands contained in the journal file. The following command 
causes VAXTPU to recover a previous editing session on an input file named 
memo.txt. If the journal file has a different name than the input file name, 
you must include both the /JOURNAL=file-spec qualifier and the qualifier 
/RECOVER with the command EDIT/TPU: 

t EDIT/TPU/RECOVER/JOURNAL=memo.gav memo.txt 

To prevent VAXTPU from keeping a journal file for your editing session, use 
the qualifier /NOJOURNAL. The following command causes VAXTPU to turn 
off journaling when you edit the input file memo.txt: 

$ EOIT/TPU/NOJOURHAL memo.txt 


6.4.5 /OUTPUT 

/OUTPUT-input—file.type (D) 

/NOOUTPUT 

Determines whether the output of your VAXTPU session is written to a 
file. The interface that is layered on VAXTPU is responsible for processing 
this qualifier. The interface can get information on whether the qualifier 
was specified when VAXTPU was invoked by using the built-in procedure 
GET-INFO, for example, x := GET-INFO (COMMAND-LINE, 'create'). For 
information on GET—INFO, see Section 4. 

In the EDT Keypad Emulator and EVE interfaces, using /OUTPUT allows you 
to name the file created from the main buffer upon exiting from VAXTPU. By 
default, the output file has the same name as that of the input file, and the 
version number is one higher than the highest existing version of the input 
file. You can specify a different name for the output file by using the file 
specification argument for the qualifier /OUTPUT. 
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The qualifier /NOOUTPUT aUows you to write an interface for VAXTPU that 
lets the user control the output of a file. For example, the interface for the 
EOT Ke)q}ad Emulator was coded so that if you specify /NOOUTPUT on 
the VAX/VMS command line, VAXTPU sets the NO_WRITE attribute for the 
main buffer and does not create an output file for that buffer. 


The following command causes VAXTPU to write the contents of the main 
buffer to the file newlet.mo when you exit from VAXTPU: 

$ EDIT/TPU/OOTPUT»newlet.rno letter.rno 


6.4.6 /READ-ONLY 

/READ-ONLY 
/NOREAD-ONLY (D) 

Determines whether VAXTPU keeps a journal file and creates an output file 
from the contents of the main buffer if you modify it. 

Using the qualifier /READ-ONLY is like using both the qualifier 
/NOJOURNAL and qualifier /NOOUTPUT. If you specify /READ-ONLY, 
VAXTPU does not maintain a journal file for your editing session, and the 
NO—WRITE attribute is set for the main buffer. When a buffer is set to 
NO—WRITE, the contents of the buffer are not written out when you leave 
VAXTPU. Both the built-in procedures EXIT and QUIT end the editing session 
without creating a new file from the contents of the main buffer (even if you 
modified it). 

If the NO—WRITE option has not been set for the buffer, /NOREAD—ONLY 
instructs VAXTPU to write the main buffer, if modified, when an EXIT 
command is issued. This is the default behavior. 

The qualifier /READ-ONLY can be used to tailor your command line 
processing. If you specify /READ-ONLY using EVE or the EDT Keypad 
Emulator, for example, a journal file is not created. The qualifier 
/NOREAD—ONLY causes the interfaces to maintain a journal file in case 
a system interruption occurs, and to create an output file when they process 
the EXIT command. 

The following command directs VAXTPU not to write out the contents of the 
main buffer when you exit from the editor: 

$ EDIT/TPU/READ.ONLY meeting.mem 




6.4.7 /RECOVER 

/RECOVER 
/NORECOVER (D) 

Determines whether VAXTPU reads a journal file at the start of an editing 
session. The default is /NORECOVER. You can get information on 
the setting of the qualifier /RECOVER by using the built-in procedure 
GET—INFO. For example, x := (COMMAND—LINE, "recover*) command 
returns a 1 (True) or 0 (False) to indicate if /RECOVER was specified when 
invoking VAXTPU. 
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If the built-in procedure JOURNAL—OPEN is executed, by default, VAXTPU 
opens the journal file for output only. If you specify /RECOVER, then 
when the built-in procedure JOURNAL—OPEN is executed the journal file 
is opened for input and output. VAXTPU opens the input file to restore 
whatever commands it contains. Then VAXTPU continues to journal 
keystrokes for the rest of the editing session or until a JOURNAL—CLOSE 
is executed. The interface that is layered on VAXTPU is responsible for 
controlling whether the built-in procedure JOURNAL—OPEN is executed. 

When you recover a session, all files must be in the same state as they were 
at the start of the editing session being recovered. All terminal characteristics 
must also be in the same state as they were at the start of the editing session 
being recovered. If you changed the width or page length of the terminal, 
you must change it back to the value it had at the start of the editing session 
you want to recover. Check especially the following values; 

• Device—Type 

• Edit—mode 

• Eightbit 

• Page 

• Width 

The following command causes VAXTPU to recover the previous editing 
session on the file notes.txt: 

$ EDIT/TPU/RECOVER notes.txt 

If the journal file has a different name than the input file name, you must 
include both the qualifier /JOURNAL=file-spec and the qualifier /RECOVER 
with the EDIT/TPU command: 

$ EDIT/TPU/RECOVER/JOURNAL-save.TJL letter.dat 

/NORECOVER is the default for VAXTPU. 


^ ^ 6.4.8 /SECTION 

/SECTION=TPUSECINI (D) 

/NOSECTION 

Determines whether VAXTPU reads a special initialization file 
that is stored in binary form. The default file type for section 
files is TPU$SECTION. By default, VAXTPU tries to read the file 
SYS$LIBRARY:TPUSECINLTPU$SECTION, the section file that creates 
the EVE interface. You can specify a different file for initialization piuposes. 
The preferred method is to define the logical name TPUSECINI to point 
to a section file other than the default file. You can also supply a full file 
specification for the qualifier /SECTION. 

The following command causes VAXTPU to read the section file 
vtlOOini.TPU$SECTION: 

t EDIT/TPU/SECTION»DISKtUSER:[SMITH]vtlOOini 

The file used as the value for /SECTION=file-spec must be compiled by 
running the source code version of your initialization file through VAXTPU 
and then using the built-in procedure SAVE. This process converts the file to 
the proper binary form. 
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If you specify /NOSECTION, VAXTPU does not read a binary initialization 
file. Unless you use the qualifier /COMMAND with /NOSECTION, 
VAXTPU has no user interface and no keys are defined. In this state, the 
only way to exit from VAXTPU is to press CTRL/Y. 


6.5 EDIT/TPU Command Parameters 

After the command EDIT/TPU at the DCL level, you can use a VAX/VMS file 
specification as a parameter. The file specification tells the operating system 
the name of the Me you want to create or edit with VAXTPU. The following 
command invokes VAXTPU with the EDT Keypad Emulator section file, and 
specifies a file named history.txt: 

$ EDIT/TPU/SECTION=SYS$LIBRARY:EDTSECINI history.txt 

When you invoke VAXTPU without a section file, VAXTPU does not require 
any parameters. However, most editing interfaces layered on VAXTPU use 
the EDIT/TPU command parameter to specify the file that is to be processed. 
For example, EVE, and the VAXTPU EDT Keypad Emulator accept one 
optional parameter, the file specification. You can start an editing session 
without specifying an input file, but, if you enter any data into a buffer, the 
editor prompts you for a file name when you attempt to exit. The syntax for 
the VAX/VMS system command that invokes VAXTPU is the following: 

$ EDIT/TPU l/qualifier,...]l [file-spec]l 

A file specification can be just the file name or a full file specification as 
shown in the following example: 

$ EDIT/TPU DISKIUSER;[SMITHJLETTEB.DAT 

Whether or not VAXTPU recognizes wildcard characters as a part of the 
input file specification depends on the interface you are using. EVE handles 
wildcard characters if there is a single match for the wildcard character. 
Otherwise, EVE does not read in a file. The EDT Keypad Emulator does not 
recognize wildcard characters. 

You do not have to include the version number as part of the file specification. 
If you do not specify a version number, VAXTPU accesses the highest version 
number in your directory. If you want to edit an earlier version, you must 
include that version's number in the file specification. 

Unless you specify the name of an output file with the qualifier /OUTPUT, 
EVE and the EDT Ke)q)ad Emulator use the input file name as the name of 
the output file. The original version of the file you are editing is not altered 
in any way. It remains in its directory unless your system manager has set a 
version limit. When you exit from VAXTPU, a new file is created in the input 
file directory (unless you specify a different directory). The file has the same 
name as the input file, but has a version number that is one more than the 
file you were editing. 
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The following VAXTPU procedures are included as samples of how to use 
VAXTPU to perform certain tasks. These procedures merely show one way 
of using VAXTPU; there may be other, more efficient ways to perform the 
same task. Make changes to these procedures to accommodate your style of 
editing. 

For these procedures to compile and execute correctly, you must be sure that 
there are no conflicts between these sample procedures and your interface. 
The following types of procedures are contained in this appendix: 

1 Line mode editor 

2 Translation of control characters 

3 Restoring terminal width before exiting from VAXTPU 

4 Defining an EDT-like keypad for the EVE interface 

5 DCL command procedure to run VAXTPU from a subprocess 


A.1 Line-Mode Editor 

The following example shows a portion of an editing interface that uses line 
mode rather than screen displays for editing tasks. This mode of editing can 
be used for batch jobs, or for running VAXTPU on terminals that do not 
support screen-oriented editing. 

! Portion of a line mode editor for VAXTPU 

! Invoked from DCL with; EDIT/TPU/NODISPUY/NOSECTION/COM>llnemode.tpu file 
! 

Input.flle :• GET.INFO (COHMAHD.LINE, 'flle_name'): I Set up main 
naln_buffer :• CREATE.BUFFER ("MAIN", Input.flle); ! buffer from Input 
POSITION (BECINNING.OF (maln.buffer)); ! file 

I 

LOOP ! Contlnuouely loop until QUIT 

end READ_LINE (•*•); 

IF end - " 

THEN 

cnd_char :• 'N*; 

ELSE 

cmd_ehar :« SUBSTK (end, 1, 1); CHANGE.CASE (cmd.ehar, UPPER); 

ENDIF; 

CASE CBd_char FROM 'I' TO 'T' ! Onl; accepting I.L.N.Q.T 
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!Top of buffer coomand 
['T']; 

POSITION (BEGINNING.OF (CURRENT.BUFFER)); 

MESSAGE (CU!UIEHT_LINE); 

INext line command 
['M'] : 

MOVE_HORIZONTAI. (-CURRENT.OFFSET); 

MOVE.VERTICAL (1); 

MESSAGE (CURRENT.LINE): 

{Insert text command 
['I']: 

SPLIT.LINE; 

COPY.TEXT (SOBSTR (cmd, 2. 999)); 

MESSAGE (CORRENT_LINE); 

{List from here to end of file command 
['L']: 

ml :» MARK (NONE): 

LOOP 

MESSAGE (CURRENT_LINE): 

MOVE.VERTICAL (1); 

EXITIF MARK (NONE) » END.OF (CORRENT.BUFFER); 

ENDLOOP; 

POSITION (ml); 

{QUIT 

['Q']: 

QUIT; 

[INRANGE,OUTRANGE]: 

MESSAGE ('Unrecognized command - enter I,L,N,Q or T'); 

ENDCASE; 

ENDLOOP; 


A. 2 Translation of Control Characters 

The following procedures are examples of how to display control characters 
in a meaningful way. This is accomplished by translating the buffer to a 
different visual format and mapping this new form to a window. On the 
VT200 series of terminals, control characters are shown as reverse question 
marks. On the VTIOO series of terminals, they are shown as a rectangle. 

! You will want to perform the initialization once during your editing 
! session If you plan to use the triuislation feature. Things which could 
! be added to this are key mappings for Initialization, prompting for 
! the buffer to be translated, and for unmapplng the translate.window 
! when you're done. 

! 

PROCEDURE Inlt.translate 

translate.buffer :• CREATE.BUFFER ('translation'); 

SET (NO.WRITE, translate.buffer): 
translate.window :» CREATE.WINDOW (1, 10, ON); 
eontrol.char.pat ANY ('TYTYYTTYYYYYTTYYYTYYYYYYYYY'); 

ENDPROCEDURE 

! This procedure performs the substitution of "meaningful characters” 

! for the single character. 

I 

PROCEDURE translate.controls (char) 

! Case from NUL to US 

! The reverse question mark Is the placeholder for control characters 
! from ASCII(O) thru ASCIKS) and ASClKld) through ASCIKSI) on the 
! VT200 series of terminals. 
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CASE char FROM •?• TO '?• 


[•f] 

COPY.TEXT 

( 

[•Y*] 

COPY.TEXT 

( 

t'Y'] 

COPY.TEXT 

( 

[•Y‘] 

COPY.TEXT 

( 

[•?•] 

COPY.TEXT 

( 

[•f] 

COPY.TEXT 

( 

[■T'l 

COPY.TEXT 

( 

['T') 

COPY.TEXT 

( 

C'T') 

COPY.TEXT 

( 

C'Y'] 

COPY.TEXT 

( 

[•f] 

COPY.TEXT 

( 

[•V] 

COPY.TEXT 

( 

C'f] 

COPY.TEXT 

( 

['T') 

COPY.TEXT 

( 

[•f] 

COPY.TEXT 

( 

['T'] 

COPY.TEXT 

( 

[•f] 

COPY.TEXT 

( 

['T'] 

COPY.TEXT 

( 

['T'] 

COPY.TEXT 

( 

['T'] 

COPY.TEXT 

( 

['T'} 

COPY.TEXT 

( 

['T'] 

COPY.TEXT 

( 

[■V] 

COPY.TEXT 

( 

['Y'] 

COPY.TEXT 

( 

['Y'] 

COPY.TEXT 

( 

['Y'] 

COPY.TEXT 

( 

[•Y-] 

COPY.TEXT 

( 

[INRANGE. OUTRANGE] 


<NUL>'): 

<S0H>'): 

<STX>•): 

<ETX>'): 

<E0T>'): 

<ENij>>): 

<ACK>'): 

<BEL>'): 

<BS>'): 

<so>'): 

<SI>'): 

<DLE>’): 

<DCi>’): 

<DC2>'): 

<DC3>'): 

<DC4>'): 

<NAK>'): 

<SyN>'); 

<ETB>'): 

<CAN>'): 

<EM>'): 

<SUB>'): 

<ESC>'): 

<FS>'); 

<GS>'): 

<RS>'): 

<us>'): 

: COPY.TEXT (char); 


ENDCASE; 

ENDPROCEDURE 

i This procedure controls the outer loop search for the special 
! control characters that we want to view 

I 

PROCEDURE view.controls (buf_name) 

LOCAL 

control.char, 
char_to_translate; 

! Vfhen the search falls we know that we have either come to the end of 
! the buffer or there were no more special characters found. 


0N_ERR0R 

POSITION (BEGINNING.OF (translate.buffer)); 

MAP (translate.wlndow, translate.buffar); 

RETURN: 

ENDON.ERROR; 

POSITION (translate.buffer); 

ERASE (translate.buffer); 

COPY.TEXT (buf.aame): i Make a copy of the original buffer 

POSITION (BEGINNING.OF (translate.buffer)); 

LOOP I Find all occurrences 

C0NTR0L.(;HAR :• SEARCH (control.char.pat, FORWARD); 

POSITION (eontrol.char); 

char.to.translate :• (RJRRENT.CHARACTER; ! Save the character 
ERASE (eontrol.char); I then erase It 

translate.eontrols (char.to.translate); I Substitute the new text 
ENDLOOP; 


ENDPROCEDURE 
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A.3 Restoring Terminal Width Before Exiting from VAXTPU 

The following procedure looks at the current width of the screen and if it 
differs from the original width, it restores the width of each window to the 
original. The screen is refreshed so that information is visible on the screen 
after you exit from VAXTPU. When all of the window widths have been 
made the same, the physical screen width is changed. 

PROCEDURE as«r_r«8tor«_8crean 
LOCAL 

origlnal_8ere«ii_ width, 
tamp.w: 

origlnal_8craaii_wldth :■ GET.INFO (SCREEN, "orlginal.widtb''); 

IF orlginal_8craan_width <> GET.INFO (SCREEN, "width") 

THEN 

tamp.w :■ gat_lnlo(window8,'llrat'); 

LOOP 

EXITIF tanp.w = 0; 

SET (WIDTH, tamp.w, orlginal.acraan.width); 
tamp.w :» GET.INFO (WINDOWS, 'naxt'); 

ENDLOOP; 

REFRESH; 

ENDIF; 

ENDPROCEDURE 

t Daflna tha kay combination CTRL/E to do an axit which 
! raatoraa tha acreen to ita original width, rapainta 
! the acreen, and then exlta. 

DEFINE.KEY ('near.reatore.acrean;EXIT', CTRL.E.KEY); 


A.4 Defining an EDT-Like Keypad for the EVE Interface 

The following procedures allow you to use an EDT-like keypad for the EVE 
interface. This is to help EOT users who do not want to learn a new keypad. 

! File EDTKEYS.TPU 

! Putting thla procedure In your aection file lata you awltch back 
! and forth between the atandard EVE keypad and em EDT-llke keypad. 

! In EVE, the commanda are; 

! tpu eveSedt.keya ! To awltch to EDT keypad 

! tpu eTeSvtlOO.kaya ! To awltch to VTIOO keypad 

! tpu evelvtSOO.kaya ! To awltch to VT200 keypad 

! 

! To Include thla In your aection file: 

! 1) Edit thla file ualng EVE 

! 2) Uaa the EXTEND TPU command (EXTEND TPU •) to compile thla file 

I 3) Uae tha SAVE EXTENDED TPU command to aave tha aection file: 

! for example, "SAVE dlak2:[uaarlmyeve.TPUtSECTION" 

! 4) Define EVE in your login.com file aa 

! ♦ EVE — "EDIT/TPU/SECTI0N-di8k2:[uaerimyeve" 

! or whatever file name you uaed in atep 3 

! 

! Then when you type EVE, the keypad changing commanda are available. 

! You can alao uae thla aa a command file by defining 

! eve == "EDIT/TPU/SECTION-EVESECINI/COMMAND-edtkeya.TPU" in your logln.com. 

! Define keyboard layout to look like EDT on VTICX) aerlea keyboarda 
PROCEDURE eveledt.keya 
! Arrow keya 

define.key ("eve_nove_left", left, "move.left"); 
define_key ("eve_move_right", right, "move.rlght"); 
define.key ("eve.move.down", down, "move.down"); 
define.key ("eve_nove_up", up, "move.up"); 
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rs 

a 


! Unshifted keys 

deflne.key (•eve.help ('keypad')", pl2, "help"); 

deflne.key ("eve.find (eTe$x_target)", pf3, "find"); 

deflne.key ("eve.erase.llne", pf4, "erase.line"); 

deflne.key ("eve.flnd (ascii (12))", kp7, "page"); 

deflne.key ("if current.direetion • forward than eve.naxt.screen * 

"else eTe.prevlous.Bcreen sndlf”, kp8, "section"); 
undaflne.kay (kpO); 

daflne.kay ("eve.erase.word", ninus, "erase.word"); 
deflne.key ("eve.forward", kp4, "forward"); 
deflne.key ("eTe_reverse", h^6, "reverse"); 
deflne.kay (*aTa.raaove", kp6, "remove"); 

deflne.key ("eva.erase.cbaracter", comma, "erase.character"); 
deflne.key ("eve.move.by.word", kpl, "move.by.word"); 
deflne.key ("eve.end.of.line", kp2, "end.of.line"); 
deflne.key ("if current.direetion - forward then eve.move.rlght " + 

"else eve_move_left endlf", kp3, "char"); 
deflne.key ("eve.move.by.llne", kpO, "move.by.llne"); 
deflne.key ("eve.select", period, "select"); 
deflne.key ("eve.retum", enter, "return"); 

! Shifted keys 

set (Bhlft.key, pfl); 

deflne.key ("execute (lookup.key(evatgat.Bhlft_key, program))", 
pfl, "sbiftkey", eve$x.uBer.keyB); 

deflne.key (*ave.help ('keypad')*, key.name (pf2, shlft.key), "help"); 
deflne.key ("eve.find (")", key.nama (pf3, shlf t.key), "find"); 
deflne.key ("eve.restore", key.name (pf4, shift.key), "restore"); 
deflne.key ("ave.do (")", key.nama (kp7, shift.key), "do"); 
deflne.key ("eve.flll.paragraph", key.name (kp8, shlft.key), 
"fill.paragraph"); 

deflne.kay ("eve.raplace (", ")", key.name (kpO, Bhlft_kay), "replace"); 
deflne.key (*eve.rastore", key.name (minus, shift.key), "restore"); 
deflne.kay ("eva.bottom", key.name (kp4, shift.key), "bottom"); 
deflne.key ("eve.top", key.name (kp5, shift.key), "top"); 
deflne.key ("eve.insart.here*, key.name (kp6, shift.key), "insert.here"); 
undeflne.kay (kay.nane (comma, shift.key)); 
deflne.kay ("ava.capltaliza.word", key.name (kpl, shift.key), 
"capltaliza.word"); 

daflne.kay ("ava.arase.llne", key.name (kp2, shift.key), "erase.line"); 
deflne.kay ("ava.quote", key.nama (kp3, shlft.key), "quote"); 
deflne.key ("ava.raplace (", '')*, key.name (enter, shift.key), "replace"); 
deflne.key (*eva.retum; eva.mova.up; ave.and.of.line", 
key.name (kpO, shift.key), **); 

deflne.key ("eve.select”, key.name (period, shlft.key), "select"); 

! Kays on main typing array 
deflne.key ("eva.deleta", del.key, "delate"); 
deflne.key ("eve.tab", tab.key, "tab"); 
deflna.key ("eve.retum", ret.key, "return"); 

daflne.kay ("eve.erasa.prevlous.word”, If.key, "arasa.pravious.word"); 
deflne.key ("eva.start.of.line", bs.key, "start.of.line"); 
deflne.key ("ave.erasa.start.of.llne", ctrl.u.key, "erase.start.of.llna”); 
deflna.key ("eve.do (")", etrl.z.key, "do"); 
deflne.key ("eve.refresh", ctrl.w_key, "refresh"); 
deflne.key ("eve.ramembar”, ctrl_r_key, "remember”); 
deflne.key (*eve.recall", ctrl_b_key, "recall"); 
deflne.key ("eve.deflne.key (")", ctrl.k.key, "deflne.key"); 
deflne.key ("ave_set_left.margin(get.info(current.buffar,'offsat.column'))", 
ctrl.a.key, "set.left.margin"); 
deflne.key ("eve.space", key.name (' '), "space”); 
evelvt200.keypad :• 0; 

ENDPROCEDURE; 

! Disable redefining DO key 
PROCEDURE evelinit.do.key 
ENDPROCEDURE; 
evatedt.keys; 
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A.5 Running VAXTPU from a Subprocess 

The following DCL command procedure shows one way of running VAXTPU 
from a subprocess. It also shows how to move to or from the subprocess. 

! 

IDCL Command Procedure to run VAXTPU trom eubproceee 

! 

iPut $ e » "Ckeptedit* 

lln your logln.com. Tbl* epavme the editor the first time 
land attaches back to it after that. I've defined a key to be 
{"attach" so it always goes back to the parent. 

$ tt • f$getdvl("sys$command","devnBm") - "_" - "_" - ":" 

t edlt.name = "Edit." ♦ tt 

$ priv.list ■ f$setprv("NOWORLD, NOGROUP") 

t pld = 0 

$10t: 

$ proc > f$get]pi(f$pid(pld), "PRCNAM") 
t if proc .eqs. edit.name then goto attach 
$ if pld .ne. 0 then goto 10$ 

$spawn: 

I priv.list ■ ffsetprv(priv.list) 

$ write syslerror "[Spawning a new Kept Editor]" 

$ define/nolog sysflnput sysicommand: 

$ tl « f$edlt(pl +""+p2+""+p3+""+p4+"" 
+p6+""+p6+""+p7+""+ p8,"COLLAPSE") 

$ spawn/process**''edit.name'* /nolog edlt/tpu 'tl' 

$ write sys$error "[Attached to DCL in directory ''f$env("DEFAULT")']" 

$ exit 
gattach: 

$ priv.list « fgaetprv(priv.list) 

$ write syslerror "[Attaching to Kept Editor]" 

$ deflne/nolog sysglnput sysicommand; 

I attach " ''edit.name'" 

I write syslerror "[Attached to DCL in directory ''f|env("DEFAULT")']" 

I exit 
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B.1 Screen-Oriented Editing on Supported Terminals 

VAXTPU supports screen-oriented editing only on terminals that respond to 
ANSI control functions and that operate in ANSI mode. By default, your 
VAXTPU session is run with the screen management file TPU$CCTSHR.EXE. 
To check your terminal setting, enter the command SHOW TERMINAL at the 
DCL level. 

VAXTPU screen-oriented editing is designed to optimize the features available 
with the DIGITAL VT200 family of terminals and the DIGITAL VTIOO family 
of terminals. DIGITAL VT52-compatible terminals are not supported for 
screen-oriented editing. Optimum VAXTPU performance is achieved on the 
VT220 and VTIOO terminals. Some of the high-performance characteristics of 
VAXTPU may not be apparent on the terminals listed in the following table 
for the reasons stated. 


Table B-1 

Terminal Behavior that Affects VAXTPU's 
Performance 

Terminal 


Type 

Characteristic 

VT102 

Slow auto-repeat rate 

VT240 

Slow auto-repeat rate 

Slower scrolling region set-up time than the VT220 

GIGI 

One form of scrolling region (VAXTPU repaints screen, rather than 
use this scrolling mechanism.) 

Auto-repeat rate not constant (Cursor keys pick up speed when 
used repeatedly.) 



B.1.1 Terminal Settings That Affect VAXTPU 

The following settings may affect the behavior of VAXTPU depending on the 
terminal that you use; 

132 COLUMN MODE 

Only terminals that set the DEC_CRT mode bit and the Advanced Video 
mode bit are allowed to alter their physical width from 80 columns to 132 
and vice versa. All other terminals keep the physical width that is set when 
you enter the editor. 

For the VAXTPU screen manager to behave predictably on GIGI terminals, 
you should report the terminal width as 84 to VAX/VMS. Use the DCL 
command SET TERMINAL/DEVICE=VK100 to set the proper terminal 
width. 
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AUTO-REPEAT ON/OFF and AUXILIARY KEYPAD ENABLING 

To take advantage of the built-in procedure SET (AUTO_REPEAT, ... ) or 
to enable the auxiliary keypad for applications mode, either DEC_CRT, or 
VKIOO, must be set. 

CONTROL SEQUENCE INTRODUCER 

A feature of VAXTPU is that it can use one eightbit control sequence 
introducer (CSI) to introduce a terminal control sequence. (Normally, the 
two character combination of the ESC key and the left bracket key ([), is 
used.) To take advantage of this feature, set your terminal to DEC_CRT2 
mode. The DIGITAL VT220 and VT240 series of terminals currently support 
this feature. 

CURSOR POSITIONING 

If your terminal sets the DEC_CRT mode bit, VAXTPU assumes that when 
control sequences that position the cursor to row 1 or column 1 are sent to the 
terminal, the 'V can be omitted. If your terminal does not behave correctly 
when it sees these control sequences, you must turn off the DEC_CRT mode 
bit. Some foreign terminals that are supposed to be VTlOO-compatible may 
not be fully compatible and may exhibit this behavior. 

EDIT MODE 

Terminals that are operating in edit mode allow the editor to take advantage 
of special edit-mode control sequences during deletion and insertion of text 
for optimization purposes. Some current DIGITAL terminals that support 
edit-mode include the VT102, the VT220, the VT240 and VT241 terminals. 

EIGHTBIT CHARACTERS 

ANSI terminals operating in eightbit mode have the ability to use the 
supplemental characters and control sequences in the DEC Multinational 
Character Set. The DIGITAL VT220 and VT240 series currently support 
eightbit character mode. If you have the eightbit mode bit set, VAXTPU 
designates the DEC Multinational Character Set into G2 and invokes it into 
GR. 

SCROLLING 

Scrolling regions are only used for terminals which have the DEC_CRT mode 
bit set. On other terminals, VAXTPU repaints the window when a scroll 
would have been used (for example, when a line is deleted or inserted). 

VIDEO ATTRIBUTES 

When you set the video attributes of windows, markers, or ranges, only those 
attributes supported by your terminal type give predictable results. Most 
ANSI CRTs support reverse video. However, only terminals that support 
DEC_CRT mode with the advanced video option (AVO) have the full range 
of video attributes (reverse, bold, blink, underline) that VAXTPU supports. 
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B.1.2 The DCL Command SET TERMINAL 

When you use the DCL command SET TERMINAL to specify characteristics 
for your terminal, set only those characteristics that are supported by the 
your terminal. If you set characteristics that the terminal does not support, 
the screen-oriented functions of VAXTPU may appear to behave in random 
fashion. For example, if you run VAXTPU on a VTIOO terminal, and you set 
the DEC_CRT2 characteristic that VTlOOs do not support, VAXTPU tries to 
use eightbit CSI controls. This could cause to appear on the screen 
where the reverse video attribute should be set. 

Most users do not knowingly set characteristics that are not supported by 
their terminal. However, if you temporarily move to a different type of 
terminal, your LOGIN.COM file may have characteristics set for your usual 
terminal that do not apply to the current terminal. This problem may also 
occur if, prior to running VAXTPU, you run a program that modifies your 
terminal characteristics without your knowledge. 

If you see unexpected video attributes or extraneous characters on the screen, 
exit from VAXTPU, and check your terminal characteristics with the DCL 
command SHOW TERMINAL. 

Recover your files with the same terminal characteristics with which your 
file was orignally created. Otherwise, a journal file inconsistency may occur, 
depending on how your interface is written. 


B.2 Line-Mode Editing on Unsupported Terminals 

If you want to run VAXTPU from an unsupported terminal, you must inform 
VAXTPU that you do not want to use the full screen capabilities. To invoke 
VAXTPU on an unsupported terminal, use the qualifier /NODISPLAY 
after the command EDIT/TPU. See Section 6.4.3 for more information on 
this qualifier. While in nodisplay mode, VAXTPU uses the RTL generic 
LIB$PUT_OUTPUT routine to display prompts and messages at the current 
location in SYS$OUTPUT. By using a combination of the built-in procedures 
READ-LINE and MESSAGE, you can devise your own line mode editing 
functions or perform editing tasks from a batch job. See the sample line 
mode editor in Appendix A. 


B.3 Terminal Wrap 

VAXTPU sets hardware wrap off to be able to manage the screen more 
efficiently. When you exit from VAXTPU, VAXTPU restores all terminal 
characteristics to the setting of the DCL command SET TERMINAL prior to 
invoking VAXTPU. If the DCL command SET TERM/NOWRAP is active, 
VAXTPU leaves the hardware wrap off. However, if the DCL command SET 
TERM/WRAP is active, VAXTPU assumes that you want hardware wrap on, 
so it turns it on, when you exit from VAXTPU. 

If you do not like this behavior of VAXTPU, you can prevent VAXTPU from 
turning on hardware wrap by specifying SET TERM/NOWRAP prior to 
invoking VAXTPU. You can enter the command interactively, or you can 
write a DCL command file that makes this setting part of your VAXTPU 
environment. The following example shows a DCL command procedure that 
is used to control this terminal setting before and after a VAXTPU session. 
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Example B-1 DCL Command Procedure for 
SET TERM/NOWRAP 


$ SET TERM/NOWRAP 

$ ASSIGN/USER SYStCOHMAND SYS$INPUT 
$ EDIT/TPU/SECTION - EDTSECINI 
t SET TERM/WRAP 
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This appendix includes a table of the messages that are produced by VAXTPU. 
The table is listed alphabetically according to the abbreviation of each 
message. In addition to its abbreviation, the table includes the actual text 
of the message, and the severity level of the message. For an explanation 
of the severity levels for messages, see the VAX/VMS System Messages and 
Recovery Procedures Reference Manual. 

The VAX/VMS System Messages and Recovery Procedures Reference Manual 
also includes a list of the VAXTPU messages. In addition, it includes the 
appropriate explanations of the messages and the suggested actions to recover 
from die errors which provoke the messages. 


Table C-1 VAXTPU Messages and Their Severity Levels 


Abbreviation 

Message 

Severity Level 

AMBIGNAME 

Variable 'name' cannot be a procedure 
at line 'integer' 

Error 

ARGMISMATCH 

Data type of first argument 
unsupported for built-in 

Error 

BADARGS 

Unrecognized argument to procedure 
at line 'integer' 

Fatal 

BADASSIGN 

Target of the assignment at line 
'integer' cannot be a function/keyword 

Error 

BADBUFWRITE 

Error occurred writing buffer 'buffer 
name' 

Warning 

BADCASE 

Unrecognized CASE constant at line 
'integer' 

Error 

BADCASELIMIT 

CASE constant outside of CASE limits 
at line 'integer' 

Error 

BADCHAR 

Unrecognized character in input on line 
'integer' 

Error 

BADDELETE 

Cannot delete static string at the line 
'integer' 

Error 

BADEXITIF 

EXITIF occurs outside of a LOOP at 
line 'integer' 

Error 

BADFIRSTLINE 

First line = 'integer', must be between 
'integer' and 'integer' 

Warning 

BADIF 

IF statement contains an assignment 
statement at line 'integer' 

Error 

BADJOUCHAR 

Expected character in journal file 

Warning 

BADJOUCOM 

Journaled command file was 'string', 
recovering with 'string' 

Warning 
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Table C-1 (Cent.) VAXTPU Messages and Their Severity Levels 


Abbreviation 

Message 

Severity Level 

BADJOUEDIT 

Journaled with edit mode 'string', 
recovering with edit mode 'string' 

Warning 

BADJOUEIGHT 

Journaled with eightbit 'string', 
recovering with eightbit 'string' 

Warning 

BADJOUFILE 

Recovery terminated due to error in 
journal file access 

Error 

BADJOUINPUT 

Journaled input file was 'string', 
recovering with 'string' 

Warning 

BADJOUKEY 

Expected key in journal file 

Warning 

BADJOULINE 

Journaled with line editing 'string', 
recovering with line editing 'string' 

Warning 

BADJOUPAGE 

Journaled page length was 'integer', 
recovering with page length 'integer' 

Warning 

BADJOUSEC 

Journaled section was 'string', 
recovering with 'string' 

Warning 

BADJOUSTR 

Expected string in journal file 

Warning 

BADJOUTERM 

Journaled terminal type was 'string', 
recovering on a 'string' 

Warning 

BADJOUWIDTH 

Journaled width was 'integer', 
recovering with width 'integer' 

Warning 

BADKEY 

'keyword' is an invalid keyword 

Error 

BADLOGIC 

Internal logic error detected 

Fatal 

BADMARGINS 

Margins specified incorrectly 

Warning 

BADPROCNAME 

Variable used as a procedure at line 
'integer' 

Error 

BADPROG 

Procedure definitions must precede 
statements in a program 

Error 

BADPROGDELETE 

Cannot delete current program at line 
'integer' 

Error 

BADREAD 

Read next or read prev with current 
record of 0, dscb: 'address' 

Fatal 

BADREQUEST 

Request, 'name', is not understood 

Warning 

BADRETURN 

RETURN occurs outside of a procedure 
at line 'integer' 

Error 

BADSTRCNT 

Invalid string count found in journal file 

Warning 

BADUSERDESC 

Descriptor from user routine invalid or 
memory inaccessible 

Error 

BADVALUE 

Integer value 'integer' is outside of 
specified limits 

Error 

BADWINDADJUST 

Attempt to make window less than 1 
line long, no adjustment 

Warning 

BADWINDLEN 

Window length = 'integer', must be 
between 'integer' and 'integer' 

Warning 
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